By contextual help we mean that the help files are related to the element that
you are browsing. For example, if you are looking at the gradebook you might
need some help to understand how it works and the contextual help will display
a little "help" link to your help topic(s).

SchoolTool is clearly separated in different components (person, group, gradebook... all the elements you see in navigation) and different views on those components (have a look at the lower left part of the menu and see all the different actions you can do on one component). A help topic will have to be related to one of these components or one of these views.

Step one: write your help files

Help files can be:

• plain text documents (txt)
• structured text documents (stx)
• restructured text documents (rst)
• HTML documents (html)
• Page template based content (pt)

Use your favourite one to write your help file.

As an example we will write here a new help topic for the "group" component, explaining what a group really is in the schooltool context.

• Go to the component code location (e.g for group go to schooltool/group).
• Create a "help" directory.
• Go inside the help directory
• Directly create the famous "__init__.py" to give python the ability to browse it.
• We write our new help topic in our first help file: group_container.stx

Be careful to give the right file extensions!

Step two: Register your help topic

Now that you have your help file, you are ready to wire it to your schooltool instance:

• Go to the component code location (e.g for group go to schooltool/group)
• Go in the help directory.
• Create configure.zcml
• Add the following register directive:

<configure
     xmlns:zcml="http://namespaces.zope.org/zcml"
     xmlns:browser="http://namespaces.zope.org/browser"
     xmlns:help="http://namespaces.zope.org/help"
     zcml:condition="have context-help"
     i18n_domain="schooltool" >

<help:register
     id="groupcontainer_index"
     title="Group Container - Contents"
     doc_path="group_container.stx"
     for="schooltool.group.interfaces.IGroupContainer"
     view="index.html"
     class="zope.app.onlinehelp.onlinehelptopic.ZPTOnlineHelpTopic" />

</configure>

• Go to the component code location (e.g for group go to schooltool/group)
• Edit the configure.zcml
• Add the following directive:

<include package=".help" />

• That's it, restart your schooltool instance, log in and click on group, you will see the famous little "help" on the top right.

Some more explanations about this help:register directive. You can specify the following attributes:

• parent - Location of this topic's parent in the OnlineHelp tree. Optional.
• id - The id of the help topic. Required.
• title - The title of the topic. It will be used in the tree as Identification. Required.
• doc_path - Path to the file that contains the topic. Required.
• doc_type - Defines the type of document this topic will be. Optional.
• for - The interface this topic apllies to. Optional.
• view - The name of the view for wich this topic is registered. Optional.
• class - The dotted path to the class which will be used for initialize a topic. Optional.
• resources - A list of resources that can be referenced by the Help Topic (e.g. images). Optional.

For more examples, read http://svn.zope.org/Zope3/trunk/src/zope/app/onlinehelp/help/README.stx?rev=29184&view=markup and the zope3 code in Zope3/src/zope/app/onlinehelp.

Step three: Help topic resources

If you want to add links to other files or images in your help topic use the resources attribute. e.g:

<help:register
      id="groupcontainer_index"
      title="Group Container - Contents"
      doc_path="group_container.stx"
      for="schooltool.group.interfaces.IGroupContainer"
      view="index.html"
      resource="screenshot1.jpg" />

As you see here we link two screenshots to our group help file.

Step four: Help topic hierarchy

Coming soon...