Help System Specification
Ian Oeschger <oeschger@brownhen.com>This document describes some changes to the way that the help system works in Mozilla 1.0. Two major updates in particular may affect the way that authors include new content, that developers provide context-sensitive help from the UI, and the way that other applications can use the help system to display their own customized help content. These changes are so significant that the existing specifications for the help viewer, listed in the References section at the end of this document, have been semi-retired.
Changes described in this document:
In addition to these two systematic changes, the look of the help window has changed somewhat. Among other things, the help window now uses sidebar-like panels on the left side to organize an enlarged set of navigation tools. These tools, described in the Sidebar section below, include a client-side search facility, a separate glossary, and a dynamically created index.
Context Key Lookups
The way that context-sensitive help works now is extremely inefficient. UI like the Preferences dialog uses the current subframe as a key for the lookup of an id number (Cf., pref-help.js, which contains the array), and then uses that id in a second lookup in the help system of the appropriate content to load when the window displays. The two lookups take extra time and create a larger margin for error, and the keys themselves, numbering in the hundreds, take up a lot of room in the build.
Additionally, this system does not provide any simple way to select the appropriate item in the table of contents on the left side of the help viewer. The way that content is loaded via RDF templates makes particular subnodes, such as nested items in the table of contents, hard to find. A better way to load context-sensitive content into the help viewer is to ask for the node you want in the RDF data, and to have that request prompt the loading of the appropriate HTML content in the content pane, which is exactly what happens when a user selects a node in the table of contents, like so:
Help button -lookup-> RDF -select-> TOC -onselect-> HTML Content
Using RDF IDs as Context Keys
Since we already have a set of unique IDs for every topic in the help in the form of ID attributes in the RDF/XML that describes the table of contents, we don't need this extra set of IDs that sits in help.js and pref-help.js. If the "contextual" part of the help system is that certain nodes in the RDF datasources are selected as the window loads, then the IDs of those nodes is all we need to select in the TOC and load the right HTML. Currently, the function for opening the help window with context looks something like this:
openHelp("chrome://help/content/help.xul?imagemap_properties");
where the string in the parentheses is the URL for the help window and the part after the question mark is the special ID that gets resolved to an anchor within the HTML content.
Instead, the URL would be something like this, where the URL is an RDF URI and the ID after the question mark is the ID of the node within the loaded datasources that should be selected.
| Syntax | openHelp(rdfuri?rdfid); |
|---|---|
| Example | openHelp("chrome://help/locale/mozillahelp.rdf?nav"); |
| Shortcut Example | openHelp("?nav"); |
The openHelp() function is defined in the next file help/content/contextHelp.js, which should be included in files elsewhere in the UI that wish to ask for the help window with a particular context. The function takes either the full RDF URI to the metafile (see the RDF metafile section below for a description of the workings of this metafile) or the ID of the item in the RDF/XML table of contents (help/locale/help-toc.rdf) that corresponds to the content that should be loaded when the help window is opened. Note that this means that every piece of content that can be opened as contextual help should be represented in the table of contents.
This obviates the need for any lookup at all and makes it possible for UI developers to create new context-sensitive help by adding RDF data that can be composed into the help, that points to their HTML content, and without having to edit the javascript files in which the help "keys" are currently defined. This new, more direct way of displaying help in the help window is part of a more general update, described in the following section, in which the overall layout and scope of the help window, including the contextual help, is defined in a main RDF file.
RDF Metafiles
The help system uses RDF in a limited way to display content in the viewer. The table of contents is an example of data that is read from a datasource and built as part of the UI. But the potential for dynamic data in the help viewer is much greater than that, and the help system needs, among other things, to be more modular, so that it can be used in other applications, so that it's easier to add HTML content and other new data, and so that the relationship of the various parts is more clear and effective. With these things in mind, Peter Wilson has come up with a prototype that uses RDF/XML to describe the help system more as a whole application. In other words, when the help.xul file loads, it looks for a metafile in which the contents of the TOC are specified, as well as the index, the searchable data, and any other modules that should be loaded as part of that set.
The metafile will look something like this:
<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:nc="http://home.netscape.com/NC-rdf#">
<!-- MOZILLA MASTER HELP DOCUMENT -->
<rdf:Description about="urn:root"
nc:title="Mozilla Help."
nc:defaulttopic="welcome"
nc:base="chrome://help/locale/">
<nc:panellist>
<rdf:Seq>
<rdf:li>
<rdf:Description nc:panelid="search" nc:title="Search" nc:datasources="rdf:null"/>
</rdf:li>
<rdf:li>
<rdf:Description nc:panelid="toc" nc:title="Contents"
nc:datasources="navigator-toc.rdf mail-toc.rdf composer-toc.rdf help-toc.rdf"/>
</rdf:li>
<rdf:li>
<rdf:Description nc:panelid="index" nc:title="Index"
nc:datasources="help-index0 help-index1"/>
</rdf:li>
<rdf:li>
<rdf:Description nc:panelid="glossary" nc:title="Glossary"
nc:datasources="help-glossary.rdf"/>
</rdf:li>
</rdf:Seq>
</nc:panellist>
</rdf:Description>
</rdf:RDF>
The defaulttopic attribute identifiers the ID of the RDF node that should be selected (which in turn loads the HTML content); the base attribute identifies a base for URLs that point into the chrome at HTML content, and the panellist structure lists the RDF files that should be built into the UI as a part of this particular set of help content. This set lists four panels, contents, index, search, and glossary, and it has the name mozillahelp.rdf to identify it as the basic metafile for the help. But you could instead load a metafile called minhelp.rdf or perhaps sansmail.rdf, and in this way provide new data or data more specific to the installation.
Sidebar Panels and Navigation Tools
An important change to the user interface of the help system is the user of sidebar-like panels in the left side of the window. Where the original help viewer had a tabbox with two panels, a table of contents and an index, the new system provides a configurable list of sidebar panels. When you include all of the available panels in the <nc:panellist> definition in your metafile, these panels include:
- Search
- Table of Contents
- Index
- Glossary
The flexibility of the metafile that defines the help system at an application-specific level, described above, allows you to include all of these panels or any subset.
Search Facility
The new help system provides a lightweight client-side search facility based upon the use of RDF/XML to define much of the structured content of the help system.
The search panel provides a simple textfield and button interface to the search facility. When you enter a term in the textfield and click the button, the search facility searches all of the RDF/XML data in the help system – including the table of contents, the glossary, and the index – for the term. It then builds a list of matches for the term in the area below. Each of the items in the list is a link to the content that corresponds to the RDF/XML in which that match was made.
Table of Contents
The table of contents, though implemented in very much the same way that it was in previous versions of the help system, has been reorganized to reflect the existence of other modes of navigation, reorganized to reflect some informal usability testing, and expanded. The table of contents is the main database against which context-sensitive help requests are resolved (see the context section above), and so all content that can be referred to in the contents pane (i.e., all HTML anchors in the HTML files) must be present in the table of contents and implemented as an RDF/XML element with a unique ID. This is because context-sensitive help requests, which used to ask for HTML content which would ask in turn for the right node in the table of contents to be loaded, now are requests for nodes in the table of contents, which then load the appropriate content into the content window. In this update, the table of contents is the main gateway between the help system and the rest of the user interface.
Index
In earlier versions of the help system, the index was a simple HTML page that was generated from special anchors in the HTML content. The script that generated the HTML index, listed in the references section below, was run against the latest versions of the help and the resulting HTML page was checked in as help-index.html.
Though the process for generating the index is the same as before, the index is now written in RDF/XML. This provides the structured index data (implemented as an outliner by means of an RDF template) in the index pane, and also provides the bulk of the database against which the seach facility does its matching. The use of RDF/XML for the index also resolves some issues with fonts and display in earlier versions of the help window and makes the panels more consistent with one another.
Glossary
The new glossary panel separates the glossary data that was already present in the old table of contents out into a separate panel. The glossary data is structured in a different way than the table of contents, and this separation acknowledges that and makes it easier to find and to navigate.