Overview

# Connecting Help in NetBeans: From Help Set Installation to Hooking up Context-Sensitive Help

This document is designed to help NetBeans module writers with installing help into the IDE and correctly setting up context-sensitive help for their modules. The document covers the following topics:

- Introduction
- Adding Help to GUI components
  - Explorer Nodes
  - Wizards
  - Dialogs
  - Property Sheets
  - Tabbed Property Sheets
  - Individual Properties
  - Custom Property Editors
  - Tabbed Custom Property Editors
  - Service Types and System Options
- Merge Hints for TOC and Index
- Making the Help Set Known to the IDE
  - Manifest File
  - Layer File
- Where to Put Help Files in the Module Source
- Additional Notes
  - Making Help IDs Unique
  - I18N of Help IDs

## Introduction

The IDE's architecture enables you to:

- Create separate help sets and associate them with given modules.
- Specify the order in which the help sets are merged, which can affect the order in which topics appear within the table of contents.
- Associate an IDE component with a specific help topic by means of a help ID for the component. When the user presses F1 or a Help button on the component, the help is displayed in the JavaHelp viewer.
- Create a separate menu item for the help set

In order to take advantage of these help features, a NetBeans module writer must be aware of different aspects of the NetBeans help system, specifically:

- How to programmatically specify which help text to display for GUI components
- How to declare the help set for the module so it will be found at runtime
- Where to include help related files in the module source so it can be checked into the CVS repository
- How to specify how the help set is built during the IDE's build process

## Adding Help to GUI components

There is an overview of adding help to various GUI NetBeans components in the JavaHelp Integration API. This section expands a bit on the information provided there.

### Explorer Nodes

If your node extends `AbstractNode` or one of its subclasses, you should implement the `getHelpCtx` method to return a `HelpCtx` for the node. The `HelpCtx` includes the specific Help ID for the help topic for this node. If the node is selected in the explorer and the user hits the F1 key, then the help associated with this node will be displayed.

    public class MyNode extends AbstractNode{
        public HelpCtx getHelpCtx() {
            return new HelpCtx("org.netbeans.modules.xml.tree.nodes.XMLDataNode");
        }
        // other methods...
    }

### Wizards

Wizards are basically a series of Swing Components that are displayed via a `WizardDescriptor.Iterator` object. The object that the developer creates must implement the `WizardDescriptor.Panel` interface which includes a method that the developer implements to return the actual Swing Component that is to be displayed (usually a `JPanel` is returned). Additionally, the developer must implement the `getHelp` method and return a `HelpCtx` for this particular wizard step. By default, the Help button is displayed on the resulting `JDialog` and when the user selects this Help button, the `getHelp` method is called for the currently displayed `WizardDescriptor.Panel` object.

    public class MyWizardPanel implements WizardDescriptor.Panel {
        private JPanel p;
        public Component getComponent() {
    	if (p == null) {
    	    p = new JPanel();
                p.setLayout(new BorderLayout());
                p.add(/* etc. */);
            }
    	return p;
        }
        public HelpCtx getHelp() {
            return new HelpCtx("org.netbeans.modules.xml.core.wizard.DocumentPanel");
        }
        // other methods...
    }

### Dialogs

There are two different ways in which you can set help on a NetBeans dialog. If you wish to display a dialog of some sort, you typically create the Swing components you wish to display and then create a `DialogDescriptor` object which is a NetBeans object that is used to describe the behavior or the dialog. To display help:

1. Specify the help on the `DialogDescriptor` object - As a rule, setting the help ID on the `DialogDescriptor` is the preferred way to set a help ID for a dialog. There are a couple of ways to do this:
   - Use one of the `DialogDescriptor` constructors that includes a `HelpCtx`.
   - Call `setHelpCtx` on the previously created `DialogDescriptor`:

         DialogDescriptor dd = new DialogDescriptor(...);
         dd.setHelpCtx(new HelpCtx("dialog_help_id"));

2. Set the help ID string on the displayed Swing Component - You'll notice that the `DialogDescriptor` constructor takes an `Object` which is typically the Swing Component to display in the `JDialog`. If you set the help ID string property on the Swing component, then this help id will be used as the help id for the `JDialog` and the corresponding help will be displayed if the user selects the Help button.

       JPanel p = new JPanel();
       // ...add Swing components to p ...
       HelpCtx.setHelpIDString(p, "panel_help_id");
       DialogDescriptor dd = new DialogDescriptor(p, "Dialog Title");

If you do not supply a `HelpCtx` object for the `DialogDescriptor` or set the help ID string for the displayed Swing Component, then no Help button will be displayed on the `JDialog` that is displayed for this `DialogDescriptor`.

### Property Sheets

When creating a Property Sheet, the developer creates a `Sheet.Set` object. To populate the `Sheet.Set` the developer creates and adds a number of `Node.Property` objects. To display help for the Property Sheet, you must call the `setValue` method and set the `helpID` property:

    Sheet sheet = Sheet.createDefault();
    Sheet.Set ps = sheet.get(Sheet.PROPERTIES);
    ps.setValue("helpID", "org.netbeans.modules.xml.tree.nodes.XMLDataNode.Properties");

### Tabbed Property Sheets

Property sheets can actually contain multiple tabs, each having their own help associated with them. The method described above to set the help id of a Property Sheet still applies, the only difference is the way in which the additional Property Sheet is created:

    Sheet sheet = Sheet.createDefault();
    Sheet.Set referenceTab = new Sheet.Set();
    referenceTab.setValue("helpID", "org.netbeans.modules.xml.tree.nodes.XMLDataNode.ReferenceProperties");
    referenceTab.setName("referenceTab"); // NOI18N
    sheet.put(referenceTab);

### Individual Properties

You can also set an individual help ID for each property (`Node.Property`) in a property sheet. Presently Sun Java Studio and NetBeans help is not provided on a per-property basis - help on individual properties is provided in the form of a tooltip.

### Custom Property Editors

Some Properties displayed on a Property Sheet require a custom editor. The user accesses the editor by selecting the "..." button on an entry for a specific Property when the user selects that Property. The developer of the custom editor provides a Swing Component (typically a JPanel) which is ultimately displayed in a `JDialog`. If Help is to be supplied on the resulting `JDialog`, then the help ID string of the supplied Swing Component must be set.

    public MyPropertyEditor extends PropertyEditorSupport{
        public Component TreeNodeFilterCustomEditor() {
    	JPanel p = new JPanel();
    	// ...add Swing components to p...
    	HelpCtx.setHelpIDString(p, "org.netbeans.modules.xml.tax.beans.editor.TreeNodeFilterCustomEditor");
    	return p;
        }
        // other methods...
    }

### Tabbed Custom Property Editors

Some Custom Property Editors display a number of tabs. Depending on the tab that is displayed, different Help may need to be displayed. In this case, you should set the help ID on the property editor's JTabbedPane. If you want the help ID to change when the user switches tabs, then you should listen for changes in the selected tab, and change the ID on the JTabbedPane each time.

For NetBeans 3.4 and earlier, you can set help IDs on tabs as shown in this example:

    class MyTabPane extends JTabbedPane implements ChangeListener {
        private HelpCtx[] helps = new HelpCtx[3];
        public MyTabPane() {
            add(new Panel1());
            helps[0] = new HelpCtx("help_1");
            // etc.
            stateChanged(null);
            addChangeListener(this);
        }
        public void stateChanged(ChangeEvent ignore) {
            HelpCtx.setHelpIDString(this, helps[getSelectedIndex()]);
        }
    }

In NetBeans releases later than 3.4, you can use the `HelpCtx.Provider` to simplify the process, as shown in the following example:

    class MyTabPane extends JTabbedPane implements HelpCtx.Provider {
        private HelpCtx[] helps = new HelpCtx[3];
        public MyTabPane() {
            add(new Panel1());
            helps[0] = new HelpCtx("help_1");
    	// etc.
        }
        public HelpCtx getHelpCtx() {
    	return helps[getSelectedIndex()];
        }
    }

### Service Types and System Options

Many modules define their own Service Types such as Ant Compilation. Additionally, many define their own System Options such as the UDDI Registries. In both cases, developers extend either the `ServiceType` or the `SystemOption` abstract class. Defined in each class is the `getHelpCtx` method. If you wish to display help for your Service Type or System Option, implement the method:

    public class AntCompilerType extends CompilerType {
        public HelpCtx getHelpCtx() {
            return new HelpCtx("org.apache.tools.ant.module.run.AntCompilerType");
        }
        // other methods...
    }

Note that the `CompilerType` class extends the `ServiceType` class.

## Merge Hints for TOC and Index

In NetBeans IDE 3.6, the help system has been upgraded to use v. 2.0 of JavaHelp software. The most visible benefit of the upgrade is better merging of TOC and index. NetBeans IDE uses the Unite-Append merge type for the table of contents and the Sort merge type for the index. These merge types are set in the master help set and propogate to any help sets that merge into the product, unless those help sets override them with other merge types. For more information on merge types, see the JavaHelp release notes.

The biggest resulting impact for module authors is the need to more carefully design TOCs and indexes so that entries from different help sets merge comprehensibly for users. Here are some general tips and rules of thumb:

- Use the most recent revision of the usersguide module index as a guide for your indexing conventions to make your entries fit in seamlessly.
- DO NOT use manual separators in your indexes, (e.g. <indexitem text="-A-"></indexitem>). These are superfluous with merged indexes are suspected of triggering a bug in JH that crashes the help system - see Issuezilla bug 39966.
- Any TOC or index entry that contains sub-entries should have no `target` attribute. This rule has been adopted because it is not possible to provide useful topics for every "bucket" and users should have a consistent experience as to when to expect a topic to display. If you feel that there is a useful introductory topic for a TOC bucket, make that topic the first entry in the bucket and call it "About". You can
- If you would like to insert entries into an existing TOC bucket, check the most recent revision of the the usersguide module TOC.
- If you organize your table of contents so that "Core IDE Help" is your first-level TOC item, your help set will be slotted in under second level buckets created by the usersguide module. Also, this ensures your real top level topics are not expanded in the JH viewer (by default, the JH viewer shows two levels of topics when first opened), thus leaving more room in the first screenful of the help viewer for other modules' high-level topics. The TOC for such a module might look like the following:

      <?xml version='1.0' encoding='ISO-8859-1'  ?>
      <!DOCTYPE toc PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN"
               "http://java.sun.com/products/javahelp/toc_1_0.dtd">
      <toc version="1.0">
      <tocitem text="Core IDE Help">
          <tocitem text="HTTP Monitor">
              <tocitem text="Monitoring Data Flow on the Web Server" target="ctx_monitorintro" />
      	    <tocitem text="Viewing HTTP Monitor Data Records" target="monitor_view" />
      	    <tocitem text="Using the HTTP Monitor Toolbar" target="monitor_sort" />
      	    <tocitem text="Editing and Replaying Monitor Data Records" target="monitor_resend" />
      	    <tocitem text="Saving HTTP Monitor Data Records" target="monitor_store" />
      	    <tocitem text="Deleting HTTP Monitor Data Records" target="monitor_delete" />
                  <tocitem text="Deploying the HTTP Monitor for a Web Module" target="monitor_servconfig" />
              </tocitem>
          </tocitem>
      </toc><

## Making the Help Set Known to the IDE

In order to use the result help set within the IDE at runtime, a couple of things need to be added to various files associated with the module. These are outlined in part in the reference documentation. This description assumes you are using a NetBeans module project.

### Manifest File

You need to add an entry to your module's manifest file in order for your help set to be used at runtime:

    OpenIDE-Module-Requires: org.netbeans.api.javahelp.Help

You can use the module's project properties dialog to add this dependency.

The projectized build process will also add a `Class-Path` entry, as the documentation will be built into a separate JAR file.

### Layer File

A module's help set must be defined in its layer file. Layer files are typically called `mf-layer.xml`, `layer.xml`, or `ModuleLayer.xml`. You can find the name of your module's layer file in the module JAR's manifest.

The layer file consists of a `filesystem` element, within which are nested various `folder` elements, where various types of information are declared. For help sets, one folder is relevant:

- Services - (Required). Used to install the help set in the IDE.

Services Folder - Insert a `JavaHelp` folder into the `Services` folder to merge the help set into the IDE's JavaHelp viewer. This mainly affects the order into which help sets are merged into the table of contents. By convention, module help sets that come with the distribution are located after the Core IDE Help (usersguide) and before third-party help. For example, this is the Services/JavaHelp entry in the layer file for the HTTP Monitor module:

      <folder name="Services">
        <folder name="JavaHelp">
          <!-- Merge after Core IDE Help: -->
          <attr name="org-netbeans-modules-usersguide-above-regular.txt/org-netbeans-modules-web-monitor-resources-helpset.xml" boolvalue="true"/>
          <!-- Merge after JSP/Servlet Help: -->
          <attr name="org-netbeans-modules-web-ie-helpset.xml/org-netbeans-modules-web-monitor-resources-helpset.xml" boolvalue="true"/>
          <file name="org-netbeans-modules-web-monitor-resources-helpset.xml" url="helpset-decl.xml"/>
          <!-- Merge before 3rd party help: -->
          <attr name="org-netbeans-modules-web-monitor-resources-helpset.xml/org-netbeans-modules-usersguide-below-regular.txt" boolvalue="true"/>
        </folder>
      </folder>

## Where to Put Help Files in the Module Source

Help files should be kept under a `javahelp` subdirectory off of the module root directory. Like source code, all JavaHelp documentation must be placed into a globally unique package to avoid conflicts. If two modules put help files into the same package, it will result in broken links. The `javahelp` subdirectory should therefore use a distinctive "package" name prefix. It is conventional to use `module.code.name.base.docs`, e.g. for a module named `org.netbeans.modules.foo`, place the JavaHelp into `org.netbeans.modules.foo.docs` (plus perhaps subpackages).

## Additional Notes

This section includes any additional comments or issues regarding Help for IDE modules.

- Making Help IDs Unique - When a Help request is initiated with a specific Help ID, the code that looks for the corresponding html file to display starts checking the help sets that have been loaded. As soon as a match is made, the html file is loaded in the JavaHelp viewer. There is no checking to see if the help set matches the module from which the request was made. So, for example, if you define a Help ID such as `node_help` and include that in two different help sets, when this Help is requested the first help set in which this ID is found will be used as the source for the corresponding html file.

  It is therefore necessary for all Help IDs to be unique. The best way to avoid collisions to preface all Help IDs with the standard package name of the module it comes from. Thus for the Execution tabs of the property sheet for a form object node, you should set the help ID to `org.netbeans.modules.form.FormDataObject.executionTabProperties` or similar.

- I18N of Help IDs - All of the `HelpCtx` methods that take strings as parameters are included in the IDE's list of NOI18N patterns and therefore are not internationalized. You do not need to add `// NOI18N` to lines containing these strings.

Questions or comments? Send to nbdev.

@FOOTER@