Adding Searchable Online Help to your NetBeans Java SE Applications

We've always found JavaHelp rather fiddly as a way of adding online help, so we have written a free PDF alternative called PDFHelp which can be downloaded from http://www.pdfhelp.org.

We wanted something which looked good, offered search, was easy to setup and could use all the existing PDF documentation for your project so it would be easy to maintain. This tutorial shows how you can use it to add Searchable help to your NetBeans applications

Part 1: Creating a New NetBeans Project

The first step - after loading NetBeans and downloading the PDFHelp jar from http://www.pdfhelp.org - is to create a new Java Application Project. From the File Menu select New Project. This will bring up a dialog box like the one below. From the "Categories" options select "Java", and from the "Projects" list choose "Java Application", then click the "Next" button.

The next dialog box to appear - as shown below - will prompt you to give a name to the new project. In this case the example project will be called "PDFHelpBean". At this stage we can also tell NetBeans not to make a default Main Class. Simply de-select the "Create Main Class" checkbox and click "Finish".

Add New JFrame

Now NetBeans has created our project, we can add the JFrame class which will ultimately hold our PdfHelpPanel component. As shown in the screen shot below, right click on the "Source Packages" folder inside the "PDFHelpBean" project. From the resulting pop-up menu select "New" -> "JFrame Form".

NetBeans will now ask you to choose a name for this new Form. In this example it will be called "PDFHelpFrame". Once you have entered the name click "Finish" and NetBeans will generate a new JFrame class.

This concludes the first part of this tutorial. You have now created a new Java Project, and added the JFrame container that will be used to house the PdfHelpPanel component. You are now ready to proceed the next part of the tutorial - Loading the PdfHelpPanel component into the Matisse component palette.

Part 2: Loading the PdfHelpPanel JavaBean Component

Once you have created a new Java Project and added a new JFrame, you are ready to add the PdfHelpPanel JavaBean component to the Matisse palette. From the "Tools" menu select "Palette" -> "Swing/AWT Components".

This will bring up a dialog box asking you where you wish to import your JavaBean from. In this case select the "Add from JAR" button.

Next, in the resulting file chooser dialog, navigate to the location where the pdfhelp.jar is stored, and click "Next".

From the list of available components choose PdfHelpPanel and click "Next".

When choosing which category to add the PdfHelpPanel component to you are free to choose any you like. For the sake of this tutorial however, "Swing Controls" is selected. When you have chosen your category, click "Finish".

When the Palette Manager reappears click "Close".

This concludes the part two of this tutorial. You have now imported the PdfHelpPanel JavaBean component into the Matisse component palette, meaning it is now ready to add to your JFrame form. You can now proceed the next part of the tutorial - Adding the PdfHelpPanel component onto a JFrame and running the application.

Part 3: Adding the PdfHelpPanel Component onto a JFrame

The first step to adding the PdfHelpPanel component, is to set the Layout Manager of the JFrame. As shown in the screen shot below, in the "Inspector" window you will see the JFrame. Right-click on it to bring up the context menu, then select "Set Layout" -> "Border Layout".

Finally, we need to set the size of the JFrame. To do this, once again locate the JFrame in the "Inspector" window, however, this time single left click on it. This will bring up the JFrame properties in the "Properties" window. As you will see in the screen shot below, there are four flavors of property a component can have; Properties, Binding, Events and Code. On this occasion select "Code".

From the "Form Size Policy" drop down box select "Generate Resize Code". Then in the "Form Size" property enter "[700, 500]".

Adding the PdfHelpPanel JavaBean

Once you have setup the JFrame, locate the PdfHelpPanel JavaBean in the component palette. In this example it is stored in the "Swing Controls" section of the palette, but it will reside wherever you told it to when you imported in.

Select the PdfHelpPanel component from the palette and drag and drop it across onto the form.

Now that the PdfHelpPanel has been added to the form, we need to add some files to the File List so the user has some PDF documents to search through. This is done through a property accessible through the Matisse Properties panel. The blue arrow in the screen shot below indicates which property to use - it is the fileLocations property. Click on the "..." button as indicated by the arrow to set the property.

The property takes an array of type String, each String indicating the individual location of each PDF document. Four types of file location are permitted, they are: -

• An absolute file path of a local location on disk
• A directory path which will be scanned recursively, adding all PDFs found to the file list
• A URL
• A classpath location

Examples are: -

• C:/file.pdf
• C:/PdfFiles/
• http://www.jpedal.org/jpedal.pdf
• jar:/com/idrsolutions/pdf/pdfhelp/res/jpedal.pdf

Matisse will display a customized dialog box allowing you to pass any number of String paths into the method. As shown in the screen shot below, in this example three location types are used: an absolute file path, a URL, and a classpath location. When you have added all the desired PDF locations, click the "OK" button.

We can now see that the PdfHelpPanel has updated its File List to include the three files added. To run the application click the green "Run Main Project" button - as indicated by the blue arrow in the screen shot below - in the NetBeans toolbar.

The first time you run the application NetBeans will tell you that the PDFHelpBean project does not have a Main Class, and it will ask you to choose one from a list. There will only be one item in the list - the PDFHelpFrame. Select it and click "OK".

Upon running the application you will see PDF Help as shown in the screen shot below. You can either customize this application further in Matisse to fit your specific needs, or you could even put this example directly into your end user applications, thereby providing the users of your software with 100% pure Java, online, searchable help.