NetBeans Platform Cookbook Chapter 02 04

Providing Help

Each module can add its own contribution to Help of the application. NetBeans uses standard Java techniques where possible so help system is based on standard JavaHelp API. The module must have a dependency to JavaHelp Integration module. It is added after you create module helpset in the IDE.


Figure 2.6 Help


Helpset which you can create by IDE contains following files (mod is module name):

  • mod-helpset.xml is located in source package and registered in the layer.xml file. It describes where help files are located by URL using nbdoc protocol. Other files are located in javahelp folder of the project folder.
  • mod-map.xml file contains mapping of the help ID to physical file by relative URL, e. g. <mapID target="" url="module-about.html"/>,
  • mod-toc.xml is table of content by pairs title – ID,
  • mod-idx.xml is an index file containing pairs text – ID,
  • mod-hs.xml is description of the helpset,
  • mod-about.html is top help page of the helpset. You can describe module function, settings, links to important themes etc. here.

Links to other help file within this module by <a href="book.html">book</a>.

Link to other module help:

<a href="nbdocs://module.package.base/path/to/source/file.html">file</a>

e. g.

<a href="nbdocs://nbpcook.helps.other/nbpcook/helps/other/docs/other-about.html">Other module</a>.

External links:

<object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer">
   <param name="content"
   <param name="text" 
         value="<html><u>Book support page</u></html>">
   <param name="textFontSize" value="big">
   <param name="textColor" value="blue">

How to

To provide your helpset create new file in Module Development category and choose file-type JavaHelp Help Set. The wizard creates JavaHelp node under project node in Project panel. It contains files mod-about.html, mod-hs.xml, mod-idx.xml, mod-map.xml and mod-toc.xml described above. There is also the mod-helpset.xml created in the module base package and registered in the layer.xml in Services/JavaHelp folder. Note how to hide unwanted helpsets:

<folder name="Services">
   <folder name="JavaHelp">

      <file name="mod-helpset.xml" url="mod-helpset.xml">
             <attr name="position" intvalue="3239"/>
      <!-- hide unwanted helpsets  --> 
            <file name="org-netbeans-modules-usersguide-helpset.xml_hidden"/>
            <file name="org-netbeans-modules-java-helpset.xml_hidden"/>
            <file name="org-netbeans-modules-apisupport-project-helpset.xml_hidden"/>
            <file name="org-netbeans-modules-profiler-helpset.xml_hidden"/>
            <file name="org-netbeans-modules-dbschema-helpset.xml_hidden"/>
            <file name="org-netbeans-modules-subversion-resources-helpset.xml_hidden"/>
            <file name="org-netbeans-modules-db-helpset.xml_hidden"/>
            <file name="org-netbeans-modules-versioning-system-cvss-resources-helpset.xml_hidden" />

The mod-helpset.xml file contains reference url <helpsetref url="nbdocs:/com/packtpub/nbpcook/help/mod/docs/mod-hs.xml"/>.

Register F1 in the layer file as a shortcut for help calling:

   <folder name="Shortcuts">
       <file name="F1.shadow">
           <attr name="originalFile" 

Create help page files. Each page register in the map and index file and any important pages in the TOC. How to make links see in the Getting ready... section.

Do not forget make your TopComponent focusable by calling setFocusable(true) in the constructor.

Associate corresponding help page ID with its component – return right help context by method getHelp() or getHelpCtx() or Sheet.setValue("helpID", "id").


To show help topic programmaticaly use:

Help hlp = Lookup.getDefault().lookup(Help.class);
        if (hlp != null) {
            hlp.showHelp( new HelpCtx(
                  "com.packtpub.nbpcook.helps.module.book_editor") );

To show external page by system browser register URLDisplayer implementation.

Displaying of more complex pages is not correct in default swing HTML browser. Open external link in system web browser is more useful. To enable call system browser you must redefine the HtmlBrowser.URLDisplayer service included in the UI Utilities module. Create new class extending this class and ask the Desktop to show URL in external browser.

This source is copied from the great book The Definitive Guide to NetBeans Platform from Heiko Böck. Thank for advice and allowing to use.

public class ExternalURLDisplayer extends HtmlBrowser.URLDisplayer{
   public void showURL(URL link) {
      try {
      } catch(Exception ex) {
         Logger.getLogger("global").log(Level.SEVERE, null, ex);
         // show the user a message dialog

To register your overriding service provider create new file named by service interface in the META-INF/services folder and type your class into it. Set position parameter to zero to prefer your implementation.

file org.openide.awt.HtmlBrowser$URLDisplayer:



Text and sources were created under NB 6.8 6.9, 7.0, 7.1, 7.2.


Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo