Child pages
  • Help settings in tool registration files
Skip to end of metadata
Go to start of metadata

Tool registration files

Each Sakai tool has a tool registration file, typically named sakai.toolname.xml. Reference documentation on tool configuration is in sakai_tool.doc

There are 4 help-related configuration settings which can be specified in the tool configuration file: help.button, help.id, help.url and help.collections.

The Charon portal (the default Sakai portal) defines 3 of these in portal/portal-api/api/src/java/org/sakaiproject/portal/api/Portal.java:

/** Names of tool config/registration attributes that control the rendering of the tool's titlebar */
private static final String TOOLCONFIG_SHOW_HELP_BUTTON = "help.button";
private static final String TOOLCONFIG_HELP_DOCUMENT_ID = "help.id";
private static final String TOOLCONFIG_HELP_DOCUMENT_URL = "help.url";

The remaining option is defined by the HelpManager in help/help-api/src/java/org/sakaiproject/api/app/help/HelpManager.java:

public static final String TOOLCONFIG_HELP_COLLECTIONS = "help.collections";

help.button

help.button controls whether the help icon is shown in the tool title bar (typically a "?"). It would be appropriate to set this to false in cases where a tool has no online help. Example:

<configuration name="help.button" value="false" />

Display of the tool help icon depends both on the individual tool settings, and whether help is globally enabled.

help.id

help.id specifies the value which is passed to the help tool when the user clicks on the tool help icon. The Help tool displays the page from the collection of help pages which has a defaultForTool value matching the help.id value. The value of help.id is usually but not always the tool id. For example Section Info's registration file is:

<?xml version="1.0"?>
<registration>
        <tool id="sakai.sections" title="Section Info" description="For managing sections within a site.">
                <category name="course" />
                <category name="project" />

                <configuration name="help.id" value="sakai.sections" />
        </tool>
</registration>

whereas Gradebook has a tool id of "sakai.gradebook.tool" but a help.id of "sakai.gradebook".

If a tool has help.id specified in its tool registration file, then the help.id can also be overridden for a specific tool placement through the Admin Sites editor. This can be used fore xample to allow two tools in the same site (for example Web Content tools) to point to different documents in Help.

help.url

help.url is an alternative to "help.id", and is a URL to the help for this tool. This allows the tool to host its help via a URL, in its own webapp or on an external server. Example:

<configuration name="help.url" value="/jsf1/help.html"/>

help.collections

(Added in Sakai 2.5)

help.collections can be used for tools to register additional sets of help content. For example the help tool itself in its registration file help/help-tool/src/webapp/tools/sakai.help.xml adds help collections for generic help topics. This is a comma-separated list of help collections as deployed to shared by a help subproject. For this example, see https://source.sakaiproject.org/svn/help/trunk/help/help/.

<?xml version="1.0"?>

<registration>

        <tool id="sakai.help" title="Help Documentation" description="The Sakai Help Tool">

                <category name="sakai.help" />

                <!-- generic help collections -->
                <configuration name="help.collections"
                        value="sakai_iframe_myworkspace,sakai_menubar,sakai_course_sites,sakai_permissions,sakai_accessibility"
                        type="final" />

        </tool>

</registration>
  • No labels