Extension points

The plugin can be extended by another plugin activated on the same WordPress server in the following ways to provide additional, bespoke functionality:

• Hide a default setting
• Add a default setting
• Add a platform setting
• Override LTI tool (e.g. to add or vary event actions)
• Change XML and JSON configurations for Canvas
• Change the homepage
• Override the available user ID scope choices

See the extension plugin written for Pressbooks instances of WordPress for a working example of how these extension points can be used.

Hide a default setting

Selected options on the settings page can be hidden by returning their IDs and default values in an array. For example, this code stops the Hide Add User menu? option from being displayed and set its value to always be checked:

function my_plugin_lti_tool_hide_options($hide_options)
{
  $hide_options = array('adduser' => '1');

  return $hide_options;
}

add_filter('lti_tool_hide_options', 'my_plugin_lti_tool_hide_options', 10, 1);

The IDs of the options which can be hidden are as follows:

• uninstallblogs - Delete LTI blogs on platform delete?
• adduser - Hide Add User menu?
• mysites - Hide My Sites menu?
• scope - Username format
• saveemail - Save email addresses?
• homepage - Homepage

Add a default setting

The settings page can be extended as in the following example which adds a text box named My Plugin setting in the General section of the page:

function my_plugin_lti_init_options()
{
  add_settings_field(
    'my_plugin_setting', __('My Plugin setting', 'my-plugin'),
    'my_plugin_lti_setting_callback', 'lti_tool_options_admin', 'lti_tool_options_general_section'
  );
}

function my_plugin_lti_setting_callback()
{
  $options = lti_tool_get_options();
  printf('<input type="text" name="lti_tool_options[my_plugin_setting]" id="my_plugin_setting" value="%s"> <label for="my_plugin_setting"></label>', esc_attr($options['my_plugin_setting']));
}

add_action('lti_tool_init_options', 'my_plugin_lti_init_options');

The value entered by a user can be manipulated before it is saved by using the lti_tool_save_options filter. The following example converts the value entered into uppercase:

function my_plugin_lti_save_setting($new_options, $current_options)
{
  $new_options['my_plugin_setting'] = strtoupper($new_options['my_plugin_setting']);

  return $new_options;
}

add_filter('lti_tool_save_options', 'my_plugin_lti_save_setting', 10, 2);

Note that the current (old) setting values are also made available in case you need to check what change has been made.

Add a platform setting

The configuration for a platform can be extended by inserting HTML into the relevant section, or by adding additional sections at the bottom of the page. The following example adds a checkbox to the General section:

function my_plugin_lti_tool_config_platform($html, $platform)
{
  $checked = checked(!empty($platform->getSetting('__my_plugin_checkbox')), true, false);
  $html['general'] = <<< EOD
    <tr>
      <th scope="row">
        My Plugin checkbox
      </th>
      <td>
        <fieldset>
          <legend class="screen-reader-text">
            <span>My Plugin checkbox</span>
          </legend>
          <label for="lti_tool_my_plugin_checkbox">
            <input name="lti_tool_my_plugin_checkbox" type="checkbox" id="lti_tool_my_plugin_checkbox" value="true"{$checked} />
               Check this box to toggle the My Plugin setting
          </label>
        </fieldset>
      </td>
    </tr>

 EOD;

  return $html;
}

add_filter('lti_tool_config_platform', 'my_plugin_lti_tool_config_platform', 10, 2);

In addition to adding the setting to the configuration page, it is also necessary to ensure that the value is saved. In addition to the data parameters which have been submitted by the user, the current options values are also passed into the method. Note that this method can also be used to set default values when no value exists or has been submitted. For example:

function my_plugin_lti_tool_save_platform($platform, $options, $data)
{
  $platform->setSetting('__my_plugin_checkbox', (isset($data['lti_tool_my_plugin_checkbox']) && (sanitize_text_field($data['lti_tool_my_plugin_checkbox']) === 'true')) ? 'true' : null);

  return $platform;
}

add_filter('lti_tool_save_platform', 'my_plugin_lti_tool_save_platform', 10, 3);

By convention, bespoke settings are saved with a prefix of __ to avoid any conflicts with the names used by the LTI Tool plugin.

The following keys should be used to indicate the different sections of the configuration page:

• general
• roles
• ltiv1p3

The HTML for all other keys is added at the bottom of the page in ascending key value order.

Override LTI tool

The LTI Tool used by this plugin can be overridden by defining a new one as an extension and making the required changes, such as a new OnLaunch method:

class My_LTI_Tool extends LTI_Tool_WPTool
{

  protected function onLaunch()
  {
    // Insert code to execute on a valid launch here
  }

}

This bespoke tool object can be applied as follows:

function my_plugin_lti_tool($tool, $db_connector)
{
  return new My_LTI_Tool($db_connector);
}

add_filter('lti_tool_tool', 'my_plugin_lti_tool', 10, 2);

Change the homepage

function my_plugin_lti_homepage($homepage)
{
  return add_query_arg('verified', 'true', $homepage);
}

add_filter('lti_tool_homepage', 'my_plugin_lti_homepage', 10, 1);

Note that the homepage is merely the path (without the leading /) and query string of the URL to which the user should be redirected; the site URL will be automatically prefixed to this value.

Change XML and JSON configurations for Canvas

The XML configuration for Canvas can be changed using the lti_tool_configure_xml filter. The following example changes the title and description of the tool:

function my_plugin_lti_configure_xml($dom)
{
  $dom->getElementsByTagNameNS('http://www.imsglobal.org/xsd/imsbasiclti_v1p0', 'title')[0]->childNodes[0]->nodeValue = 'My Tool';
  $dom->getElementsByTagNameNS('http://www.imsglobal.org/xsd/imsbasiclti_v1p0', 'description')[0]->childNodes[0]->nodeValue = 'Access to My Tool using LTI';

  return $dom;
}

add_filter('lti_tool_configure_xml', 'my_plugin_lti_configure_xml', 10, 1);

The JSON configuration for Canvas can be changed using the lti_tool_configure_json filter. The following example changes the title and description of the tool:

function my_plugin_lti_configure_json($configuration)
{
  $configuration->title = 'My Tool';
  $configuration->description = 'Access to My Tool using LTI';

  return $configuration;
}

add_filter('lti_tool_configure_json', 'my_plugin_lti_configure_json', 10, 1);

Override available the user ID scope choices

The available user ID scope choices can be overridden using the lti_tool_id_scopes filter. The following example, only allows the global or username scopes to be made available:

function my_plugin_lti_tool_id_scopes($id_scopes)
{
  $my_plugin_id_scopes = array();
  $my_plugin_id_scopes[strval(Tool::ID_SCOPE_GLOBAL)] = $id_scopes[strval(Tool::ID_SCOPE_GLOBAL)];
  $my_plugin_id_scopes[LTI_Tool_WP_User::ID_SCOPE_USERNAME] = $id_scopes[LTI_Tool_WP_User::ID_SCOPE_USERNAME];

  return $my_plugin_id_scopes;
}

add_filter('lti_tool_id_scopes', 'my_plugin_lti_tool_id_scopes', 10, 1);