File:  [mozdev] / calendarhelp / www / extensions.html
Revision 1.4: download - view: text, annotated - select for diffs - revision graph
Fri Oct 7 12:13:36 2005 UTC (12 years ago) by whiteley
Branches: MAIN
CVS tags: HEAD
fix typo

<!-- MAIN CONTENT -->
<h5 class="page-header">Help for extensions</h5>

<p>
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.
</p>

<p>
Calendar Help includes documentation for extensions in two ways:
</p>

<ul>
<li>
An appendix in the help describes extensions very briefly
and provides links to their home pages.
</li>
<li>
An extension that the user has installed can optionally add its own chapter to the help.
</li>
</ul>


<h5>How to get your extension listed in the appendix</h5>
<p>
To have your extension listed in the appendix, open a
<a href="http://www.mozdev.org/bugs/enter_bug.cgi?product=calendarhelp">CalendarHelp bug</a> with a subject
like "Help for Foo extension", where Foo is the name of your extension.
</p>

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


<h5>How to add your own help chapter</h5>
<p>
To add your own help chapter, prepare the chapter as an xhtml file similar to
Calendar Help's other chapters.
</p>

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

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

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

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

<p>
The path to the installed help file in your extension should be like:
<pre style="margin-left:2em;">
chrome://foo/locale/help.xhtml
</pre>
where foo is the internal name of your extension.
</p>

<p>
This usually means that you store the file as:
<pre style="margin-left:2em;">
locale/en-US/foo/help.xhtml
</pre>
You can suuport other locales in the normal way by creating translated
help files in other locale directories.
</p>

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

<pre style="margin-left:2em;">
em:helpURL="chrome://foo/locale/help.xhtml"
</pre>


<h5>Linking your extension's user interface to the help</h5>
<p>
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.
</p>

<p>
A link is defined by a <tt>context</tt> 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.
</p>

<p>
The default <tt>context</tt> tag for each window specifies an element id
that is the same as the window id.
</p>

<p>
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.
</p>


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

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

<p>
To enable the F1 and Help keys, include key definitions something like these:
</p>

<pre style="margin-left:2em;">
&lt;keyset&gt;
  &lt;key id="key_openHelp" keycode="VK_F1"
    oncommand="if (opener.openHelp) openHelp(null, null, document)"/&gt;
  &lt;key id="key_openHelpMac" keycode="VK_HELP"
    oncommand="if (opener.openHelp) openHelp(null, null, document)"/&gt;
  &lt;/keyset&gt;
</pre>

<p>
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:
</p>

<pre style="margin-left:2em;">
if (!opener.openHelp) {
  // help is not installed, so hide your Help button
  }
</pre>

<p>
Specify that your Help button calls <tt>openHelp(null, null, document)</tt> when it is pressed.
</p>

<h5>Example: Calendar Folders</h5>
<p>
The Calendar Folders extension is an example of an extension that contains its
own help chapter.
</p>

<p>
You can see its <tt>install.rdf</tt> here:
<a href="http://www.mozdev.org/source/browse/calendarhelp/src/calfolder/install/install.rdf?rev=1.2">install/install.rdf</a>.
Note the <tt>em:helpURL</tt> property.
</p>

<p>
You can see the source code for its help chapter here:
<a href="http://www.mozdev.org/source/browse/calendarhelp/src/calfolder/locale/en-US/calfolder/help.xhtml?rev=1.1">locale/en-US/calfolder/help.xhtml</a>.
Note how:
</p>

<ul>
<li>
The h1 tag's id matches the internal name of the extension, <tt>calfolder</tt>.
</li>
<li>
Every heading tag has an id.
These ids are required to make the table of contents and the search feature work.
</li>
<li>
The <tt>index</tt> tags specify additional search terms.
</li>
<li>
The <tt>context</tt> tags specify links from the user interface.
</li>
<li>
The default link from Calendar Folders' own properties dialog is to the heading
<b>Using properties dialogs</b>.
</li>
</ul>

<p>
You can see the XUL source code for its dialog window here:
<a href="http://www.mozdev.org/source/browse/calendarhelp/src/calfolder/content/calfolder/properties.xul?rev=1.2">content/calfolder/properties.xul</a>
Note how:
</p>

<ul>
<li>
The <tt>dialog</tt> element specifies a help button (in the <tt>buttons</tt> attribute).
</li>
<li>
The help button runs JavaScript code (in the <tt>ondialoghelp</tt> attribute).
</li>
<li>
There are <tt>key</tt> tags for the F1 and Help keys.
</li>
<li>
The JavaScript code for the Help button and the help keys is in a separate file.
</li>
</ul>

<p>
You can see the JavaScript source code for its dialog window here:
<a href="http://www.mozdev.org/source/browse/calendarhelp/src/calfolder/content/calfolder/properties.js?rev=1.1">content/calfolder/properties.js</a>
Note how:
</p>

<ul>
<li>
A <tt>help</tt> function calls the main window's <tt>openHelp</tt> function, if it exists.
</li>
<li>
If there is no <tt>openHelp</tt> function in the main window, then the <tt>init</tt>
function hides the Help button.
</li>
</ul>

<hr style="margin-top:2em;">

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>