Adding Help to Your Tool

This document describes the process of adding help documentation to your tool. The help created using this process will show up when users click the help icon within a tool frame. Help is context sensitive (somewhat), and will open to the default help page for your tool when help is opened from within your tool itself.

Prerequisites and Assumptions

This document assumes you have all source code required to compile a working tool using Maven 1.0.2. All directory and file references will use the shorthand TOOL_SRC_DIR to refer to the root directory of your tool's source code. The shorthand "tool.id" will be used to refer to the unique tool ID, while "toolid" will be used to represent the same id without the dividing period. The shorthand "Tool Name" will be used to refer to the end-user wording that describes the tool's name.

This document will describe setting up two total help pages, one default page and a subordinate page. Instructions will be provided for extending this to include multiple subordinate pages.

Directory and File Listing

The following directories and files are required for this example:

TOOL_SRC_DIR/toolid-help/
TOOL_SRC_DIR/toolid-help/project.xml
TOOL_SRC_DIR/toolid-help/src/sakai_toolid/
TOOL_SRC_DIR/toolid-help/src/sakai_toolid/help.xml
TOOL_SRC_DIR/toolid-help/src/sakai_toolid/tooliddefault.html
TOOL_SRC_DIR/toolid-help/src/sakai_toolid/toolidsub.html

project.xml

The project.xml file controls how maven will build and deploy this portion of the tool. The ultimate goal is to create a jar that will deployed into TOMCAT_HOME/shared/lib/. This can be accomplished using a project.xml file whose contents are along these lines:

<?xml version="1.0" encoding="UTF-8"?>

<project>
    <pomVersion>3</pomVersion>
    <extend>../../master/project.xml</extend>
    <name>Tool Name Help</name>
    <id>sakai-toolid-help</id>
    <currentVersion>${sakai.version}</currentVersion>

    <properties>
        <deploy.type>jar</deploy.type>
        <deploy.target>shared</deploy.target>
    </properties>

    <build>

      <sourceDirectory>src</sourceDirectory>

      <resources>
        <resource>
          <directory>src</directory>
        </resource>
      </resources>

    </build>
</project>

help.xml

The file help.xml is a kind of packing list for all the html files that are displayed by the help tool. It controls which page is the default and lists all subordinate pages in the table of contents in the display order desired.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>
   <bean id="toolidDefault" class="org.sakaiproject.component.app.help.model.ResourceBean">
      <property name="docId"><value>tooliddefault</value></property>
      <property name="name"><value>Tool Name Default Help Page</value></property>
      <property name="location"><value>/sakai_configviewer/tooliddefault.html</value></property>
      <property name="defaultForTool"><value>tool.id</value></property>
   </bean>

   <bean id="toolidSubordinate" class="org.sakaiproject.component.app.help.model.ResourceBean">
      <property name="docId"><value>toolidsub</value></property>
      <property name="name"><value>Tool Name Subordinate Help Page</value></property>
      <property name="location"><value>/sakai_configviewer/toolidsub.html</value></property>
   </bean>

    <bean id="org.sakaiproject.api.app.help.TableOfContents" 
          class="org.sakaiproject.component.app.help.model.TableOfContentsBean">
      <property name="name"><value>root</value></property>
      <property name="categories">
         <list>
            <bean id="announcementCategory" class="org.sakaiproject.component.app.help.model.CategoryBean">
               <property name="name"><value>Tool Name</value></property>
               <property name="resources">
                  <list>
                     <ref bean="toolidDefault"/>
                     <ref bean="toolidSubordinate"/>
                  </list>
               </property>
            </bean>
           </list>
         </property>
       </bean>
</beans>

A few things to note:

The values for the bean IDs must match exactly the bean attributes listed in the property list of the table of contents.
The locations used in the bean properties are relative to the root of the help jar, which will effectively start with the directory TOOL_SRC_DIR/src/sakai_toolid.
There can be as many subordinate pages as you like, just make sure they have unique ids and filenames.
Any subordinate pages you wish to be displayed in the help tool must be listed in the table of contents.

tooliddefault.html

As with the subordinate page described below, this file must be a valid and well-formed HTML file, along these lines:

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html><head>
<title>Tool Name: Overview</title>
<style type="text/css">
/* Style for specific inline images */
		
/* Style for specific ordered lists */
		
/* Style for specific table cells */
</style>
<link type="text/css" href="/library/skin/tool_base.css" media="all" rel="stylesheet" />
<link type="text/css" href="/library/skin/default/tool.css" media="all" rel="stylesheet" />
</head>
<body>
<div class="helpBody">
<h2>Tool Name: Default Page</h2>
<h3>Introduction</h3>
<p>This is the default page users will see when they launch the help tool by clicking the help icon 
(<img src="sample.gif"/>) from within your tool.</p> 
</div>
</body>
</html>

toolidsub.html

For the purposes of demonstration, here is a sample version of toolidsub.html:

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html><head>
<title>Tool Name: Subordinate Page</title>
<style type="text/css">
/* Style for specific inline images */
		
/* Style for specific ordered lists */
		
/* Style for specific table cells */
</style>
<link type="text/css" href="/library/skin/tool_base.css" media="all" rel="stylesheet" />
<link type="text/css" href="/library/skin/default/tool.css" media="all" rel="stylesheet" />
</head>
<body>
<div class="helpBody">
<h2>Tool Name: Subordinate Page</h2>
<h3>Introduction</h3>
<p>This is a subordinate page.</p>
</div>
</body>
</html>