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 use @HelpSetRegistration.

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". 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 an 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.

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 should be constructed with a help ID, which should be a string constant uniquely identifying the feature, and associated with an HTML page using the map file.

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

public HelpCtx getHelpCtx() {
    return new HelpCtx("my.action");
}
Now the map file should include a line such as:
<mapID target="my.action" url="this-action.html"/>

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

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

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 = Lookup.getDefault().lookup(Help.class);
if (help != null && help.isValidID(id, true)) {
    help.showHelp(new HelpCtx(id));
} else {
    Toolkit.getDefaultToolkit().beep();
}

However for most purposes you can use the simpler HelpCtx.display method and avoid a direct dependency on this API entirely:

String id = ...;
if (id != null && !new HelpCtx(id).display()) {
    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 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:

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 (and in fact recommended) 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>