Apache NetBeansModule Helpset Integration FAQs
- Module Helpset Integration FAQs
- How do I open a helpset programmatically?
- 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 check links between help files and between metadata and help files?
Module Helpset Integration FAQs
How to Create a Help Set in a Module
-
In the IDE, right-click the node of the project to which you want to add the help set and choose New | Other.
-
In the Module Development category, choose JavaHelp Help Set and complete the wizard.
See also the documentation on NetBeans JavaHelp Integration API.
What Modules are the NetBeans Help Sets In?
Search http://deadlock.netbeans.org/hudson/job/nbms-and-javadoc/lastSuccessfulBuild/artifact/nbbuild/build/generated/layers.txt for Services/JavaHelp/ to find all current help sets.
An easier place to search is the Online Help section of the latest Documentation Table, such as NB71DocumentationTable#OnlineHelp_Updates.
How do I determine the order in which a help set appears in the help viewer?
The order in which help sets are merged is determined by a position attribute in the help set module’s layer file. The higher the number, the lower the position. See the list above for the numbers assigned to the current help sets.
To change the position of a help set:
-
Open the help module’s XML layer file, which is in the module’s /src directory.
-
Change the "intvalue" value of the help set’s "position" attribute.
How should I set help IDs?
See this document: help-guide
This document boils down to two ways to set a help ID:
-
By creating a new HelpCtx object with <pre>new HelpCtx(ThisHelpCtxInstanceId)</pre>
-
In a property sheet, with a call to <pre>Sheet.Set.setValue("HelpId", "ValueOfThisHelpId")</pre>
The Help id can be any string but the string must be unique throughout your code. If you are creating a HelpCtx object, you can create the help id dynamically using PanelClassName.class or PanelClassName.getClass(). For example,
public class MyBeautifulDialogPanel {
...
public HelpCtx getHelp() {
return new HelpCtx(MyBeautifulDialogPanel.class)
}
}would return the full class name of MyBeautifulDialogPanel as a help id. Be warned that doing this risks you breaking the help mapping if you ever refactor the class.
Multiple Forms in a Single Panel Class
Sometimes a single panel class can create multiple forms, using a boolean or an enum. You can dynamically create a separate help id for each of these forms. For a boolean, use this code, where BaseHelpId is a unique string and booleanVariable is the variable that determines which form is generated:
public Help Ctx getHelp() {
return HelpCtx("BaseHelpId." + booleanVariable);
}For an enum, use this code, where BaseHelpId is a unique string and the variable enumVariable has been assigned to the enum:
public Help Ctx getHelp() {
switch (enumVariable) {
case EnumValue1: return new HelpCtx("BaseHelpId.EnumValue1");
case EnumValue2: return new HelpCtx("BaseHelpId.EnumValue2");
...
default:
return new HelpCtx("BaseHelpId.default");
}
}In the mapping file, make sure to add a mapping for every value of the enum plus a mapping to default help in the default case where no enum value is set.
Mapping Help IDs to Help Files
Every help set has a Map file. Every help ID should have a unique entry in one and only one help set in your code (A program can have many help sets, as is the case with NetBeans IDE). The entry is a mapID element, and is of the form:
<mapID target="UniqueHelpId" url="PathFromMapFileToHelpFileInHelpSet"/>How do I find unmapped help IDs?
You can debug CSH help IDs by running the IDE with:
-J-Dorg.netbeans.modules.javahelp.level=100The IDE then prints the help ID of each component you press F1 on, or of the Help button in a wizard, in the console/log and tells you if the help ID was not found in the map file.
You can view the output straight from the IDE. Choose View | IDE Log File.
Note: You can add the switch to the NetBeans default switches. Edit INSTALLATION_DIRECTORY/etc/netbeans.conf. If you want to risk editing your .conf file, that is!
How do I open a helpset programmatically?
Once you have defined a mapID in the map-file
<map version="2.0">
<mapID target="myPluginAboutMapID" url="myplugin-about.html"/>
</map>You can open the topic via
new HelpCtx("myPluginAboutMapID").display();How do I link to a page in a separate helpset?
The best way is to use the nbdocs URL protocol, where the "host name" field is the code name base of the other module, and the rest is a resource path (such as from the src/ or javahelp/ directories in the source project). For example:
<a href="nbdocs://org.netbeans.modules.db/org/netbeans/modules/db/docs/connectdb.html">Connecting
to a Database</a>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.
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 (minus any /number). The list above gives the abbreviated code name bases of the help modules in the left column.
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 (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/org/netbeans/modules/usersguide/ide.css"
type="text/css">How do I check links between help files and between metadata and help files?
There are special Ant targets for this purpose that you can run from inside of the IDE.
To check links in individual help sets (including links in and validity of metadata files):
-
Make sure that you have the nbbuild module checked out. You get this automatically if you have a clone of the repository.
-
In your help set, right-click the build.xml file for the help set and choose Run Target > check-javahelp. (If you are unsure about which build.xml file applies to the help set, look at the list linked to above to determine the location of the module containing the build.xml file.)
To check inter-helpset links:
-
Clone the entire NetBeans main repository.
-
Right-click the 'nbbuild' module’s build.xml file and choose Run Target > build-nozip. Now the sources are built. Go get coffee. Do not continue with this procedure unless the build succeeds (see Output window for info).
-
Now, on the build.xml file again, choose Run Target > check-javahelpbin.
NOTE - This latter check is based on built modules. If you make or update changes in the files, you have to rebuild the modules before the changes will be recognized by the link check. Running the check-javahelp target for the module that you have updated does the trick (you do not necessarily have to rebuild the whole IDE).
