Skip to main content

Help Viewer Content API

This document describes how to integrate HTML help documentation into your application using the Mozilla Help Viewer. Documentation contained in the Help Viewer can be accessed using any XUL application or program that embeds Mozilla.

Draft 1.2.2
R.J. Keller

Table of Contents

What is a Content Pack?

A Content Pack is a directory of files that can be used to display Help content in the Mozilla Help Viewer for your XUL Application. Content Packs include a set of HTML help documentation, RDF index, and RDF glossary information. You can display multiple content packs in the Help Viewer or you can inherit an existing Mozilla Help content pack to a content pack you create.

Contents of a Content Pack

Content Packs consist of a basic Project RDF file (usually called yourApp.rdf), Table of Contents and Index RDF files, and your help documents (written in HTML, XHTML, etc.). Your main content pack file (yourApp.rdf) contains information about the location of your Table of Contents RDF file, Index RDF file, and any Search databases you may have. it can also contain variable values to help integrate the Help Viewer with your application.

To create a basic content pack file, create a basic RDF file.

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:nc="http://home.netscape.com/NC-rdf#">

    <rdf:Description about="urn:root">
    </rdf:Description>

</rdf:RDF>

The attributes of the Description tag contains attributes describing the help menu and the content displayed in it. Here is a list of attributes and the purpose they serve:

  • nc:title - The title of the help window (ex. "Mozilla Help").
  • nc:defaulttopic - The default topic of your help window. Topics are discussed later on. The default topic is loaded when the Help Viewer is first initialized and the topic is also loaded when the user hits the Home button.
  • nc:base - The place where all of your content pack files are located at (ex. "chrome://help/locale/")

Setting up a Glossary, Index, and Table of Contents

To set up the Index, TOC, and glossary, add a <nc:panellist> tag to your document. Inside of there, you will have <rdf:li> tags that will contain information that tells the Help Viewer the location of your files.

        <nc:panellist>
            <rdf:Seq>
                <rdf:li>
                    <rdf:Description nc:panelid="glossary"
                        nc:datasources="chrome://help/locale/firebird-glossary.rdf"/>
                </rdf:li>

The RDF code above tells the Help Viewer where to get the glossary from. To use the default Mozilla glossary that is shipped with the Help Viewer, set the nc:datasources attribute equal to chrome://help/locale/help-glossary.rdf.

                <rdf:li>
                    <rdf:Description nc:panelid="index"
                        nc:datasources="myApp-index.rdf"/>
                </rdf:li>
                <rdf:li>
                    <rdf:Description nc:panelid="toc"
                        nc:datasources="help-toc.rdf firebird-toc.rdf"/>
                </rdf:li>

Above is the RDF code that contains the location of the Index and Table of Contents. Just type in the name of the RDF file to load. Note that the RDF file should be located in the directory where you set nc:base above in the Creating a Content Pack section.

                <rdf:li>
                    <rdf:Description nc:panelid="search"
                        nc:datasources=""
                        nc:emptysearchtext="[No matching items found.]"
                        nc:emptysearchlink="chrome://help/locale/welcome.xhtml#search_tips"/>
                </rdf:li>

Above contains information about the Help Search. Here are the attributes and what they mean:

  • nc:datasources - Extra RDF files that you would like to search. Note that the Help Table of Contents, Index, and Glossary are searched by default, so you only need to add in any other RDF files that may contain other search strings you would like to pop up.
  • nc:emptysearchtext - The text to be displayed when no search results were found.
  • nc:emptysearchlink - The location of the help file that should be loaded if the user clicks on the nc:emptysearchtext text. You can set this value to chrome://help/locale/welcome.xhtml#search_tips if you wish to display the search tips that comes with Mozilla Help.

Creating an Index, Table of Contents, or Glossary file.

Index, TOC, and Glossary files are done in the RDF file format, just like the main content pack file.

If you do not know RDF, go see the W3C RDF Tutorial.

You use <rdf:Description> to create the main topics. Inside you will have a <nc:subheading> and <rdf:Seq>. You then use <rdf:li> tags with a <rdf:Description> tag to create each item.
Attributes for <rdf:Description> are described below:

  • ID: The title of the topic. You can use this to load a specific topic into the help window. See Launching Help Viewer below for information on how to do this.
  • nc:name: The text to display in the Table of Contents or Index file.
  • nc:link: The help file to link to. (Ex. " chrome://myApp/locale/help/myApp.xhtml")

See Appendix A for an example of a RDF entry.

Launching the Mozilla Help Viewer with your Content Pack

To launch the Mozilla Help Viewer with your content pack, you need to have contextHelp.js loaded into your XUL file. This file is located at chrome://help/content/contextHelp.js in the Mozilla Help directory.

<script type="application/x-javascript" src="chrome://help/content/contextHelp.js"/>

This will allow you to access all of the Mozilla Help Viewer functions. To open the Help Viewer, run the openHelp() function. The parameters are described below:

  • Topic to Load - The topic to load into the help window. If the help window is already displayed with this content pack, you can set this to a different value to change the topic displayed on the screen.
  • Content Pack File - The location of the content pack to load.

You can also set the Help Viewer's default content pack through the setHelpFileURI function. This function takes in a string value of the location of your content pack.

setHelpFileURI("chrome://help/content/help.xul")

Then you can launch the Help Viewer with a topic by running the openHelp() function, taking in only the name of the topic you wish to load.

openHelp("navigator")

Here is an example of how Mozilla Help launches its help documentation into the help viewer:

openHelp('using-mozilla', 'chrome://help/locale/mozillahelp.rdf');

Inheriting elements from other content packs

If you would like to add the Table of Contents, Index, or Glossary of another content pack's RDF files to your own, just add in the name of the other content pack's RDF files next to your own. For example:

                <rdf:li>
                    <rdf:Description nc:panelid="index"
                        nc:datasources="myApp-index.rdf other-index.rdf"/>
                </rdf:li>
                <rdf:li>
                    <rdf:Description nc:panelid="toc"
                        nc:datasources="help-toc.rdf firebird-toc.rdf"/>
                </rdf:li>

This content pack will contain the RDF files help-toc.rdf and firebird-toc.rdf in its content pack Table of Contents, and contain its myApp-index.rdf and other-index.rdf for its Index. The same can be done with glossary.

There will be a global content pack called the "Help on Help" content pack that will be provided globally which will contain a pre-defined glossary, and help files that will tell the user how to use the Mozilla Help Viewer.

Contact Pack RDF References

Screenshot (just mouse over)

myApp.rdf - General Content Pack File

myApp-toc.rdf - Content Pack Table of Contents File

myApp-index.rdf - Contact Pack Index file.

myApp-overlay.xul - File that launches the content pack

Feedback is welcomed.