This is an old revision of the document!
Table of Contents
Context-Sensitive Help
Introduction
The trunk version of Evergreen has re-instated the top-level Help menu in the upper right of the staff client, next to the Admin menu. It has one menu entry, For Active Tab, which will look for help files based on the URL of the interface loaded in the active tab (the tab currently being displayed beneath the menu system). If no files are found, it will display an alert, No Help Found. The idea is that you can define a hierarchy of help files, with the Help menu looking for the most specific (context-sensitive) help file first, and then gradually working its way up to more generic help files. So, we could define a global "catch-all" help file to prevent the No Help Found alert.
The help menu will look for canonical/stock help files (none of which currently exist), and for custom/localized help files, with the local files displaying first. We could implement the local help files in such a way that they augment or pull in the stock help files, but there are no templates or infrastructure currently to make that easy for us. We could also rework the Help menu code so that it loads all located help files in a tabbed interface, rather than just stopping at the first (and most specific) one that it finds. In the long term, such Help displays may include functionality for displaying indexes and for searching all documentation in its entirety.
For now, it's simply looking HTML files, which may be merely text with simple mark-up, or dynamic interfaces using Javascript. To determine which files are being looked for for a given interface, perhaps the easiest thing to do is to invoke the Help menu with the debug console enabled.
Example
Let's consider this example, using the acq.open-ils.org server and staff client, which have been built using a snapshot of the trunk version of Evergreen (this server is publicly accessible, just use the information and client listed here, and be sure to enable the debug console).
If we bring up the Check In interface, we will see a line like this in the debug console:
set_help_context: {"protocol":"http:","hostname":"acq.open-ils.org","port":"","pathname":"/xul/acq_20100513/server/circ/checkin.xul","src":""}
This lets us know that the context for the Help->For Active Tab menu entry has changed, and that it will look for help files revolving around the source file server/circ/checkin.xul.
If we active that menu entry these lines will appear in the console, and we should receive a No Help Found alert:
help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/circ/checkin.xul.custom_help.html> help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/circ/checkin.xul.help.html> help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/circ/custom_help.html> help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/circ/help.html> help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/custom_help.html> help widget: testing <http://acq.open-ils.org/xul/acq_20100513/server/help.html> help widget: testing <http://acq.open-ils.org/xul/acq_20100513/custom_help.html> help widget: testing <http://acq.open-ils.org/xul/acq_20100513/help.html> help widget: testing <http://acq.open-ils.org/xul/custom_help.html> help widget: testing <http://acq.open-ils.org/xul/help.html> help widget: testing <http://acq.open-ils.org/custom_help.html> help widget: testing <http://acq.open-ils.org/help.html>