Module Helpset Integration FAQs

• How do I hook up CSH for a dialog or UI element?
• How do I link to a page in a separate helpset?
• How do I merge helpsets?
• How do I merge into an existing TOC and index category?
• Are there guidelines for creating TOC and Index entries?
• How do I create a glossary item in the help?
• How do I make a link to an external web page open in the IDE's external web browser?
• How do I link to the common CSS for the IDE?

How do I hook up CSH for a dialog or UI element?

See this document: http://www.netbeans.org/download/41/javadoc/JavaHelpAPI/org/netbeans/api/javahelp/doc-files/help-guide.html

How do I link to a page in a separate helpset?

The best way is using the following syntax:

 <a href="nbdocs://module_name/path_to_page_from_javahelp_directory">  

Example:

<a href="nbdocs://org.netbeans.modules.db/org/netbeans/modules/db/docs/connectdb.html">Connecting
to a Database</a><br>

The module name should be the name of the module containing the helpset. The name is listed in the OpenIDE-Module property of the module's JAR file. When you use this format, the IDE displays an error message if the module is not installed. Otherwise broken inter-helpset links do not do anything in the IDE.

If you know that the module helpset will always be installed (i.e., usersguide helpset) you can use the simple form:

 <a href="nbdocs:/path_from_javahelp_dir"> Example: <a href="nbdocs:/org/netbeans/modules/db/docs/connectdb.html">

How do I merge helpsets?

Helpsets are merged automatically by the IDE's master helpset. You don't need to specify mergetypes for the views of your helpset.

How do I merge into an existing TOC and index category?

In your TOC file, copy the TOC category structure exactly as it exists in the usersguide module TOC file (http://www.netbeans.org/source/browse/usersguide/javahelp/org/netbeans/modules/usersguide/ide-toc.xml). Then place your listing in the desired category.

For example, say you wanted to list a help file under the Java Project Basics -> Building Java Applications category. You would enter the following in your TOC file:

   <?xml version='1.0' encoding='ISO-8859-1'  ?>
   <!DOCTYPE toc PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 2.0//EN"
            "http://java.sun.com/products/javahelp/toc_2_0.dtd">
   
   <toc version="2.0">
      <tocitem text="Java Project Basics">
          <tocitem text="Building Java Applications">
              <tocitem text="My Help File" target="my_target" /> 
          </tocitem>
      </tocitem>
   </toc>

"My Help File" would get merged in at the end of the topics in the category.

The same technique works for indexing. To merge into the "databases" index category, do the following:

<indexitem text="databases" > 
    <indexitem text="MyCoolDB, connecting to" target="connectMyCool" />
</indexitem>

Are there guidelines for creating TOC and Index entries?

• If possible, try to merge your helpset into the existing TOC categories and index categories. For example, if you are developing a server plugin, merge it into the Servers and Databases > Servers category.
• In general, put all of your topics into a TOC category. There should never be individual topic entries as first-level entries in the TOC.
• Don't have your category nodes linked to a topic. If there is a general intro topic for your section, put it as an About page underneath.

  WRONG

   <tocitem text="My Cool Plug-in" target="myCoolPlugin">    ... </tocitem>

  RIGHT:

   <tocitem text="My Cool Plug-in" > <tocitem    text="About My Cool Plug-in" target="myCoolPlugin" />    ... </tocitem>

How do I create a glossary item in the help?

Create the glossary page. The page should have an <h6> title in lower case capitalization, for example:

  <h6>standard project</h6> 
  <p>A project that uses an IDE-generated Ant script to compile, run, and debug...

Note: Glossary topics shouldn't be listed in the Table of Contents.

Use the following syntax to link to the glossary page:

      <object classid="java:com.sun.java.help.impl.JHSecondaryViewer">
         <!-- Enter the link to the glossary page below-->
          <param name="content" value="../project/csh/glossary_standard.html">
          <param name="viewerActivator" value="javax.help.LinkLabel">
          <param name="viewerStyle" value="javax.help.Popup">
          <param name="viewerSize" value="400,220">
         <!-- Enter the display text below-->
         <param name="text" value="standard Java project">
          <param name="textFontSize" value="small">
          <param name="textFontFamily" value="SansSerif">
          <param name="textFontStyle" value="italic">
          <param name="textFontWeight" value="bold">
          <param name="textColor" value="blue">
      </object>

How do I make a link to an external web page open in the IDE's external web browser?

Use the following syntax:

      <object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer">
         <!-- Enter the URL below -->
          <param name="content" value="http://www.netbeans.org/kb/41/freeform-config.html">
          <!-- Enter the display text below. The <html> and <u> make the text look like a link. -->
          <param name="text" value="<html><u>http://www.netbeans.org/kb/41/freeform-config.html</u></html>">
          <param name="textFontSize" value="medium">
          <param name="textColor" value="blue">
      </object>

Note: When you view the page outside of NetBeans, this link will not display or will display as a ???

How do I link to the common CSS for the IDE?

Each helpset should use the ide.css that is included in the usersguide module. Linking to the common CSS lets vision-impaired users make changes to the help font and backgroung colors. Use the following link in your HTML pages:

 <link rel="StyleSheet" href="nbdocs:/org/netbeans/modules/usersguide/ide.css" type="text/css">