Geertjan's Blog

  • September 8, 2008

Dealing with Helpsets from 3rd Party JARs

Geertjan Wielenga
Product Manager
Let's say you have an application on top of the NetBeans Platform. One of the application's modules does nothing more than wrap a 3rd party library. However, within that 3rd party library is a helpset that you'd like to integrate into your own application's helpset. How do you integrate that helpset, i.e., one that is within a 3rd party JAR, into your own application?

You could, of course, simply manually copy the help files from the 3rd party helpset and paste them into one of the modules in your suite that already provides a helpset. That solution presents two problems, however. Firstly, you now have the same HTML files in two places—within the 3rd party JAR as well as within the module that integrates them into the application's helpset. That's not very convenient and your application is now potentially much larger than it needs to be. Secondly, what happens when the JAR is updated? The helpset is then potentially modified and you'll need to copy them over again, again manually. Not convenient either.

So the better solution is to add an Ant script to your build process. The Ant script will, at whatever point in your build process that it is convenient to do so, unjar the 3rd pary JAR, create a scratch folder, copy the complete content of the 3rd party JAR into the scratch folder, and then copy the relevant folder (i.e., the 'help' folder) into the module that will provide the helpset. So long as the "helpsetref" tag in your helpset.xml file points to the "hs" file that is expanded into the module, everything will work seamlessly and you'll have a single source for the helpset. In other words, you'll not check any help topics into your CVS. Instead, you'll recreate the helpset on the fly, as needed, and the HTML files will always be within the JAR file:

<target name="create-marvin-help" description="Get help topics from JAR">
<property name="help.dir" location="../modules/MarvinHelp/javahelp/com/im/ijc/marvinhelp/help"/>
<property name="scratch.dir" location="../modules/MarvinHelp/scratch"/>
<delete dir="${help.dir}"/>
<mkdir dir="${help.dir}"/>
<mkdir dir="${scratch.dir}"/>
<unjar src="../libraries/JChem/release/modules/ext/jchem.jar" dest="${scratch.dir}"/>
<copy todir="${help.dir}">
<fileset dir="${scratch.dir}/help">
<include name="\*\*"/>
<delete dir="${scratch.dir}"/>

The downside of this approach is that you now have no control over the helpset at all, since you're simply unjarring it on the fly. In other words, you need to take the settings and content provided by the JAR as given, there's no way for you to change them. For example, if 'expand=false' is not set in the TOC, and you don't want the top node to be expanded, there's nothing you can do since you're using the TOC from the JAR, rather than one you have control over within your module.

Join the discussion

Comments ( 4 )
  • Jesse Glick Monday, September 8, 2008

    Better still would be to leave the original JAR completely untouched. Most easily: create a library wrapper module for the JAR, make it not be autoload, add a dep on the token org.netbeans.api.javahelp.Help, and add the one-liner XML file to the module's layer that registers the helpset. Done - no custom build.xml.

  • Geertjan Monday, September 8, 2008

    Sure, that would be the ideal solution. But the help files are still inside the JAR. So how would they end up in the library wrapper module's helpset?

  • Jesse Glick Monday, September 8, 2008

    Because making a lib wrapper module automatically adds the lib to the module's "classpath", meaning you can refer to the .hs file using a regular Java resource path (nbresloc URL protocol, for example).

  • Geertjan Wednesday, September 10, 2008

    Thanks a lot. That works perfectly. Much (much) better solution than mine.

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.