Overview

# NetBeans JavaHelp Integration API

It is possible to add JavaHelp and context help capabilities to modules. This API module makes that possible. It also includes the JavaHelp standard extension library itself.

## JavaHelp installation

### Helpset registration

You can add JavaHelp via your XML layer. First you need to add the helpset to the IDE. This has several effects: it ensures that context help can use your helpset; it enabled help links to use help IDs defined in this helpset; and assuming the helpset is marked to be merged into the master helpset, this means that the menu item Help | Contents will show any navigators you define in your helpset, merged into others.

To add a helpset, you must register an object implementing `javax.swing.HelpSet` into the IDE's lookup system. The normal way to do this is to create an XML file with a special DTD which you place into the `Services/JavaHelp/` folder of the system filesystem via layer. This file specifies the URL to the help set, for example:

    <?xml?>
    <!DOCTYPE helpsetref PUBLIC
              "-//NetBeans//DTD JavaHelp Help Set Reference 1.0//EN"
              "http://www.netbeans.org/dtds/helpsetref-1_0.dtd">
    <helpsetref url="nbresloc:/org/netbeans/modules/foo/help/HelpSet.hs"/>

By default such a helpset will be merged into the IDE's master help navigators. You may opt out of this by specifying `merge="false"` on the `<helpsetref/>`. If providing a custom help set instance via lookup, in order to turn off merging you should set the "key data" on the helpset with the context `OpenIDE` and key `mergeIntoMaster` to `Boolean.FALSE`.

Using `nbresloc` implies that the helpset can be found in the module's classloader, for example in its main JAR or in an extension ZIP or JAR referenced via the `Class-Path` manifest attribute. There is a URL protocol `nbdocs` which is similar to `nbresloc` and will load anything it can. It also will try to load localized resources using `InstalledFileLocator` with a prefix of `docs/`. Given the current implementation of the NetBeans installation structure, this will permit the help set and associated files to reside in a package hierarchy underneath the `docs/` folder (of the IDE installation or user directory), if not in the module classloader.

### Shortcut registration

To add a shortcut to a specific help ID in your help set, there is a different XML DTD you can use. The shortcut XML specifies the help ID to display (which must be present in some registered help set of course), for example:

    <?xml?>
    <!DOCTYPE helpctx PUBLIC
              "-//NetBeans//DTD Help Context 1.0//EN"
              "http://www.netbeans.org/dtds/helpcontext-1_0.dtd">
    <helpctx id="org.netbeans.modules.foo.some-topic"/>

By default such a link will display a help window containing navigators only for the help set from which it was taken. If you prefer to display navigators for all merged help sets, specify `showmaster="true"` on the `<helpctx/>`.

This XML file's only use is that it has a menu/toolbar presenter which opens the specified help page. (You can customize its display name and icon using the normal means available to templates etc.) You could provide an alternate means of displaying help shortcuts, however the functionality of showing the master navigators is only accessible via the presenters of this kind of XML file.

Note that usage of help shortcuts is no longer recommended by NetBeans style guidelines.

### Module dependency

Note that JavaHelp capability is not automatically guaranteed to modules. Rather, modules supplying JavaHelp documentation which wish to ensure that this documentation will be visible, must declare an explicit dependency on the JavaHelp library. This library provides the capability `org.netbeans.api.javahelp.Help`, so a module may declare the dependency as follows:

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

## Context Help

When the help set is specified in the module, this permits the IDE to associate context help with various features associated with the module (or, technically, other modules - if you know their help IDs and they do not themselves bind them). There are several ways to associate help IDs with module features so that they may be used by the IDE, mostly revolving around the API class `HelpCtx`.

This class has several constructors for different purposes; the constructor which takes a `Class` is convenient for some purposes, or the one taking a `String` is also fine. The constructor with a string directly uses that help ID, which may be any string uniquely identifying the feature, and associated with an HTML page using the map file; when passing in a class object, this should typically be the class returning the help object, and the ID will be the fully-qualified class name, which avoids the need to separately choose a good help ID.

For example, a system action might include a method implementation such as:

    public HelpCtx getHelpCtx() {
        return new HelpCtx(ThisAction.class);
    }

Now the map file should include a line such as:

    <mapID target="com.mycom.mymodule.ThisAction" url="this-action.html"/>

There are a number of different points in the APIs where you may specify a `HelpCtx` in this fashion:

- `Node.getHelpCtx()`
- `DataObject.getHelpCtx()`
- `TopComponent.getHelpCtx()`
- `SystemAction.getHelpCtx()`
- `NewType.getHelpCtx()`
- `PasteType.getHelpCtx()`
- `DialogDescriptor.getHelpCtx()`
- `WizardDescriptor.Panel.getHelpCtx()`
- `SystemOption.getHelpCtx()`
- `ServiceType.getHelpCtx()` (applies equally to executors and compiler types)

There are some other points where you may specify a help ID directly:

- On any (Swing lightweight) component you use in a GUI, by means of `HelpCtx.setHelpIDString(...)`. This is especially useful for custom property editor components.
- On any JavaBean, by adding the help ID as a (string) value to the (`FeatureDescriptor`) attribute named `helpID` in a `BeanDescriptor`, as described by the JavaHelp specification in regards to beans. This will be interpreted by any bean container (e.g. `InstanceDataObject` or `BeanNode` or `*.ser` files) that uses `InstanceSupport.findHelp(...)`.

  This technique may also be used to add context help support to the editor kits used in the Editor API; create the bean info for the subclass of `EditorKit`, and this help will be used for the editor pane.

  As of NetBeans 3.4, you may also use the attributes `propertiesHelpID` and `expertHelpID` on the `BeanDescriptor` in order to specifically supply help for regular (resp. expert) property sets only. To provide a specific help for just one property, use `helpID` on the `PropertyDescriptor`.

- As the `helpID` value of a `Node.PropertySet` or `Node.Property`.
- For services on the system filesystem (typically installed via layer) and the folders they are in (typically beneath `Services/`), you may use the file attribute `helpID` to specify the help ID right in the layer. See the Services API for details.
- In the `<homeID>` tag of a help set file; in this case, the specified help ID is understood as applying generally to the module. Typically it should be some sort of index page.
- In various navigational views used by JavaHelp, such as the table of contents or the index.

The proper help page for the selected component, if there is one, is displayed by the IDE by default using `F1`. This applies to various visual components (when they have focus), the current `TopComponent`, and nodes (or the objects they represent) when the node is selected in an Explorer window (or custom windows using `ExplorerUtils`). Programmatically, you may also display help by using the JavaHelp module API:

    String id = ...;
    Help help = (Help)Lookup.getDefault().lookup(Help.class);
    if (help != null && help.isValidID(id, true).booleanValue()) {
        help.showHelp(new HelpCtx(id));
    } else {
        Toolkit.getDefaultToolkit().beep();
    }

If you are having trouble figuring out why you are not seeing the help you expect, try running the IDE with the command-line option `-J-Dorg.netbeans.modules.javahelp=0` and look in your `system/ide.log` file for details. `-J-Dorg.openide.util.HelpCtx=0` may also be used to get further information on association between help IDs and GUI components, and so on.

## External links in JavaHelp

Most of external links are not displayed correctly in internal java help viewer. This lightweight component was added to invoke default IDE HTML browser (it should be external browser). This component can be included in HTML content within JHContentViewer. Component is displayed as a mouse enabled Label. Only text is supported.

To use this class within HTML content use the <object> tag. Below is an example usage:

    <object CLASSID="java:org.netbeans.module.javahelp.BrowserDisplayer">
        <param name="content" value="http://www.netbeans.org">
        <param name="text" value="Click here">
        <param name="textFontFamily" value="SansSerif">
        <param name="textFontSize" value="x-large">
        <param name="textFontWeight" value="plain">
        <param name="textFontStyle" value="italic">
        <param name="textColor" value="red">
    </object>

or to get hyperlink style use:

    <object CLASSID="java:org.netbeans.modules.javahelp.BrowserDisplayer">
        <param name="content" value="http://java.sun.com/downloads/ea/index.html">
        <param name="text" value="<html><u>Early Access</u></html>">
        <param name="textFontSize" value="medium">
        <param name="textColor" value="blue">
    </object>

HTML is used to get underlined text and value of text parameter must be properly escaped.
Valid parameters are:

- content - a valid external url like http://java.sun.com
- text - the text of the activator.
- textFontFamily - the font family of the activator text.
- textFontSize - the size of the activator text font. Size is specified in a css termonolgy. Acceptable values are as follows:
  - xx-small
  - x-small
  - small
  - medium
  - large
  - x-large
  - xx-large
  - bigger - increase the current base font size by 1
  - smaller - decrease the current base font size by 1
  - xxpt - set the font size to a specific pt value of "xx"
  - +x - increase the current base font size by a value of "x"
  - -x - decrease the current base font size by a value of "x"
  - x - set the font size to the point size associated with the index "x"
- textFontWeight - the activator text font weight. Valid weights are
  - plain
  - bold
- textFontStyle - the activator text font style. Valid font styles are
  - plain
  - italic
- textColor - the activator text color. The following is a list of supported Color names
  - black
  - blue
  - cyan
  - darkGray
  - gray
  - green
  - lightGray
  - magenta
  - orange
  - pink
  - red
  - white
  - yellow

## Extension of nbdocs protocol

As documentation is modular ie. it is defined across modules it is possible to define link in documentation from one module to another module. When referred module is not present or is not enabled such link becomes invalid. We extended nbdocs protocol to handle such case by frendlier way. Now it is possible to place at URL host name position base name of referred module. Instead of

    nbdocs:/org/nb/mod/foo/docs/somepage.html

it is possible to use:

    nbdocs://org.nb.mod.bar/org/nb/mod/foo/docs/somepage.html

where `org.nb.mod.bar` is module base name. Referred module is checked if it is present and enabled in IDE. If yes link is handled as usual. If not informational page is created and displayed. Page template is located at `core/javahelp/src/org/netbeans/modules/javahelp/resources` as `notEnabledModule.html` and `notInstalledModule.html` so they can be localized.
Example: In Users Guide module there is link to HTTP Monitor module:

    <a href="nbdocs:/org/netbeans/modules/web/monitor/docs/monitor/ctx_monitorintro.html">
    Monitoring Data Flow on the Web Server</a>

After adding module base name it will be:

    <a href="nbdocs://org.netbeans.modules.web.monitor/org/netbeans/modules/web/monitor/docs/monitor/ctx_monitorintro.html">
    Monitoring Data Flow on the Web Server</a>

@FOOTER@