Tool Settings

Tool Settings service

LTI 2.0 introduced a tool settings service. Settings can be instantiated at three different levels in the tool consumer:

• consumer
• context
• resource link

Each of these entities has a getToolSettings and a setToolSettings method. For example, at the resource link level, they can be used as follows:

use IMSGlobal\LTI\ToolProvider\Service;

$settings = $resource_link->getToolSettings();

Let us assume that the current settings are in place:

Level	Name	Value
System	level	consumer
System	consumer	top
Context	level	context
Context	context	middle
Resource link	level	link
Resource link	link	bottom

In this case, the above method call would have returned the following array:

array (
  'level' => 'link',
  'link' => 'bottom',
)

That is, a simple array containing all the settings for the resource link. This is equivalent to:

$settings = $resource_link->getToolSettings(Service\ToolSettings::MODE_CURRENT_LEVEL, TRUE);

If the simple parameter is set to FALSE then the level will be included in the result array. That is,

$settings = $resource_link->getToolSettings(Service\ToolSettings::MODE_CURRENT_LEVEL, FALSE);

would generate a result array of:

array (
  'link' => 
  array (
    'level' => 'link',
    'link' => 'bottom',
  ),
)

Settings for all the higher levels could have been included as follows:

$settings = $resource_link->getToolSettings(Service\ToolSettings::MODE_ALL_LEVELS, FALSE);

which would have returned:

array (
  'link' => 
  array (
    'level' => 'link',
    'link' => 'bottom',
  ),
  'context' => 
  array (
    'level' => 'context',
    'context' => 'middle',
  ),
  'system' => 
  array (
    'level' => 'consumer',
    'consumer' => 'top',
  ),
)

Note that passing a value of TRUE for the simple parameter would have resulted in the method returning a value of FALSE as the array cannot contain settings from different levels with the same name. However, it is possible to request only settings with distinct names (for those with the same name, the setting at the lowest level will be included):

$settings = $resource_link->getToolSettings(Service\ToolSettings::MODE_DISTINCT_NAMES);

This would return:

array (
  'level' => 'link',
  'link' => 'bottom',
  'context' => 'middle',
  'consumer' => 'top',
)

and

$settings = $resource_link->getToolSettings(Service\ToolSettings::MODE_DISTINCT_NAMES, FALSE);

would return:

array (
  'link' => 
  array (
    'level' => 'link',
    'link' => 'bottom',
  ),
  'context' => 
  array (
    'context' => 'middle',
  ),
  'system' => 
  array (
    'consumer' => 'top',
  ),
)

The setToolSettings method takes a simple array of the setting names and values for the level at which the method is being called.

Setting extension service

The doSettingService($action, $value = NULL) method is used to retrieve, save and delete data in the tool consumer resource link.

$setting = $resource_link->doSettingService(ToolProvider\ResourceLink::EXT_READ);

Note that the setting value may also be obtained from the settings of the ResourceLink (use getSetting('ext_ims_lti_tool_setting')). This value is automatically updated whenever a new setting is saved.

$setting = 'Please remember this ...';
$ok = $resource_link->doSettingService(ToolProvider\ResourceLink::EXT_WRITE, $setting);
...
$ok = $resource_link->doSettingService(ToolProvider\ResourceLink::EXT_DELETE);