mozdev.org

CalendarHelp

resources:
developer:
project:
projects:

This page is for developers writing extensions for Mozilla Calendar and Sunbird. It applies only to Calendar Help version 0.6.1 and later versions.

Calendar Help includes documentation for extensions in two ways:

How to get your extension listed in the appendix

To have your extension listed in the appendix, open a CalendarHelp bug with a subject like "Help for Foo extension", where Foo is the name of your extension.

In the bug report, provide a link to your extension's home page.

How to add your own help chapter

To add your own help chapter, prepare the chapter as an xhtml file similar to Calendar Help's other chapters.

The help file starts with a standard header. Do not change anything in this header:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"[
  <!ENTITY % dtd0 SYSTEM "chrome://calendarhelpres/content/parent.dtd"> %dtd0;
  <!ENTITY % dtd1 SYSTEM "chrome://calendarhelp/locale/help.dtd"> %dtd1;
  ]>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
  <link rel="stylesheet" type="text/css" href="chrome://calendarhelp/skin/helpFileLayout.css"/>
  <script type="text/javascript">const thisAppID = "&thisAppID;";</script>
  <script type="text/javascript" src="chrome://calendarhelp/content/helpContent.js"/>
  </head>
<body>

Follow this with your h1 tag containing the name of your extension, and your HTML documentation. Your h1 tag's id must match your extension's internal name.

Heading tags h2, h3, and h4 must have ids (unique within your chapter) to allow the table of contents and search feature to work. They can optionally contain index tags to define additional search terms, and context tags to define links from the product user interface. For more information about Calendar Help source files, see Guidelines for writers.

The path to the installed help file in your extension should be like:

chrome://foo/locale/help.xhtml
where foo is the internal name of your extension.

This usually means that you store the file as:

locale/en-US/foo/help.xhtml
You can suuport other locales in the normal way by creating translated help files in other locale directories.

In your extension's install.rdf, specify the path using the helpURL property, in a similar way to the other ...URL properties. For example:

em:helpURL="chrome://foo/locale/help.xhtml"
Linking your extension's user interface to the help

Calendar Help supports links from the user interface to specific help topics. The source of each link is a document element in a window. The target of each link is a heading in the help.

A link is defined by a context tag in the help. This tag specifies the source window id and the element id. Place the tag inside the heading that is the target of the link.

The default context tag for each window specifies an element id that is the same as the window id.

If your UI is overlaid on existing product windows, then you do not need to do anything more. Calendar Help overlays code in all the existing windows to enable the help.

Enabling help in additional windows

If your extension provides additional windows, dialogs or wizards, then you must provide code to enable the help in each of them.

Your code must check that Calendar Help is installed, by testing for the presence of the openHelp function in the main window. In the case of a dialog, the main window is typically available in the opener property of the global object. In other cases you might have to write code to find the main window.

To enable the F1 and Help keys, include key definitions something like these:

<keyset>
  <key id="key_openHelp" keycode="VK_F1"
    oncommand="if (opener.openHelp) openHelp(null, null, document)"/>
  <key id="key_openHelpMac" keycode="VK_HELP"
    oncommand="if (opener.openHelp) openHelp(null, null, document)"/>
  </keyset>

Include a Help button, but also include code to hide it or disable it if no help is installed. This code must run after your window is loaded, so that it can access the Help button:

if (!opener.openHelp) {
  // help is not installed, so hide your Help button
  }

Specify that your Help button calls openHelp(null, null, document) when it is pressed.

Example: Calendar Folders

The Calendar Folders extension is an example of an extension that contains its own help chapter.

You can see its install.rdf here: install/install.rdf. Note the em:helpURL property.

You can see the source code for its help chapter here: locale/en-US/calfolder/help.xhtml. Note how:

You can see the XUL source code for its dialog window here: content/calfolder/properties.xul Note how:

You can see the JavaScript source code for its dialog window here: content/calfolder/properties.js Note how:


The calendarhelp project can be contacted through the mailing list or the member list.
Copyright © 2000-2017. All rights reserved. Terms of Use & Privacy Policy.