Posted by elevy on January 15, 2008 at 10:22 AM PST
I don't know about you, I thought JavaHelp was not ready. To my surprise, it works really well. In this blog, I describe some details of how I am using it.
Being a server side developer, never had to worry about "help". I mean, about how to provide help to the users of my applications. They were simply just another JSP with ... well that's not what I want to blog about this time.
I have been working with client side Java for a while now, learning different interesting things that you can do with Swing. The time came to put together a "help".
As I always do, before writing a line of code, I started to google around to find out how others have done it. Other people had to include their help in the rich Java client applications at some point right?.
I found a project called JavaHelp. I started reading about it. All I could find was extremely old. All the documentation seemed to be outdated. I wondered, is this project still alive? is this the way to go?
I continued doing more research, and I decided I had to give it a try. I downloaded a open source authoring tool, which did not end up being really good. That's why I will not bother mentioning it in here.
Continuously reading any documentation I was able to find, encountered some Java code on how to call the JavaHelp system.
Finally, got it to work.
Then, discovered that you can generate indexes for including the search capabilities. And you know what? it works great!!!!
As I mentioned before the documentation was not really good.
To get started, just create your content in HTML. Use a page per section of your help.
Then you need to create some configuration files to define how the table of contents is going to be structured, and what are the views that you want to include.
Here is what I did:
1) Created the helpset definition file: master.hs
Table of Contents
2) Create the table of contents in the toc.xml file
3) Create the mapping file. As you probably saw in the step 2, each of the entries in the table of contents references the documents with ids. Those ids are defined in the mapping file that references the real file. Here is a sample one:
4) Create the index (only if you want to use the search, which I recommend).
Where chapters is the directory where you have your content. It will go recursively through the directory structure and index all the files.
Note that jhindexer has to be in the PATH env variable. It is installed at the bin directory of the JavaHelp distribution.
Now all you have to do is call from your Java code the help component.
All the documentation I found uses the broker to create the JavaHelp component. It is like a level of indirection between your code and the code that creates and opens the JavaHelp dialog. The problem is that you don't have control over the dialog it generates. You can not set the icons, you can not get to the GlassPane if you want to do something fancy there.
I did a little bit of scanning in the source code (open source advantage!) and found that there is a class called JHelp. It is a Swing component that does everything you will need.
Here is my Java code that opens the JavaHelp window:
There are others things I read about that I haven't tried. You can merge different help files dynamically. In this way the user can to install some modules at this time, then later when the other modules are downloaded/installed you can merge dynamically the help for those new modules.