The following outlines how help will be configured in Sakai 2.0:
1) Each tool can have a package of help material. It will be stored in the source as a separate project, one per tool (or we can have a package of help for many tools in a single project, that would work too). The tool help material include:
- a help.xml file in a path related to the tool's well known id, such as:
/sakai_chat/help.xml
the sakai.chat" well known id would be modified to replace the dot with an underbar, for a valid package name.
The help.xml has the registration for the tool's help contents, as before, with one change - the location property points to a class path rather than a URL for each help content html.
- each content help.html file would live next to the help.xml, in the .jar, on the classpath, such as:
/sakai_chat/cchd.html /sakai_chat/ccxe.html /sakai_chat/chqd.html ...
None of these, the xml nor the html, would be accessible via URL from the server. Just by classpath.
These would be organized as files under /src/help/ and the project.xml for maven would be told how to put them into a jar. These jars would deploy to shared.
2) The HelpManager is changed to use the ToolManager (not the ServerConfigurationService) to get a list of registered tools. It does this when first invoked, not when first loaded, so that all the webapps have had a chance to load and the tools are registered. It uses each tool's well known id to find that tool's (optional) "tool_id/help.xml" resource on the class path, and if found, loads up the content meta data.
3) The Help Tool is changed. First, it will extend the JsfTool servlet to have it's own version that handles dispatching. Second it will change the URLs it uses so that the URL from the content area of the display at the end user's browser points back to the help tool, encoded to indicate that it's the /content/sakai.chat display for example. The servlet front end for the Help tool will dispatch these by finding the meta data registered for this tool, finding the .html file in the class path, and streaming it back to the response.
If the meta data for a help topic has in it's "location" attribute a URL, then the help tool will respond to the /body/sakai.chat sort of request with a redirect to this URL. Otherwise it will find it on the classpath and stream it.
Hence the content can be set to live outside of the deployment of Sakai.