Integrating help into an Eclipse RCP does not require a lot of work. Simply use the ActionFactory to add the help menu item to an existing menu in your ApplicationActionBarAdvisor class:
IWorkbenchAction helpAction = ActionFactory.HELP_CONTENTS.create(window); // in makeActions(IWorkbenchWindow window)
register(helpAction); // registration is required
menu.add(helpContentAction); // add it to the desired menu
And voilà, the help menu entry is visible. Click on it, and nothing happens… The reason is easy to guess, the Eclipse help plug-ins are missing. Since the help system changed quite a lot with Eclipse 3.3, the list of required plug-ins differs between the different Eclipse versions. So the following applies to Eclipse 3.4 only.
Some of the required plug-ins are easy to guess:
org.eclipse.help
org.eclipse.help.base
org.eclipse.help.ui
org.eclipse.help.webapp
Doing a dependency check on those (with the Validate Plug-ins button in the run configuration) brings up quite a long list, which really blows up your RCPs’ size. OK, some of them are required by the RCP anyway. While some of the required plug-ins are obvious, others are not:
javax.servlet
javax.servlet.jsp
org.apache.commons.el
org.apache.commons.logging
org.apache.jasper
org.apache.lucene
org.apache.lucene.analysis
org.eclipse.equinox.http.jetty
org.eclipse.equinox.http.registry
org.eclipse.equinox.http.servlet
org.eclipse.equinox.jsp.jasper
org.eclipse.equinox.jsp.jasper.registry
org.eclipse.osgi.services
org.mortbay.jetty
In case you do have a plug-in based product configuration you can simply add the required plug-ins. In this case make sure that the checkbox for the optional plug-ins is selected before clicking the Add required plug-ins button. Or use your run menu entry to add the required plug-ins for you.
Before launching your RCP again make sure that at least one of your plug-ins does provide some help content. Otherwise the help system will show up empty.
Now that we do have a working help system, let’s open some help pages directly. This may be necessary in an Eclipse Form based editor (like the Plug-in Manifest Editor) where a help icon in the upper right directly accesses the help system.
Simply create a command with a contribution item (or an action if you like the old style) and place the following code in the run method:
PlatformUI.getWorkbench().getHelpSystem().displayHelpResource("/de.xmlsicherheit.sample/help/overview.html");
de.xmlsicherheit.sample is the plug-in id as defined in the manifest. Do not forget the leading slash! Now a click on the button, icon or whatever you decide to use will open the help system and directly jump to the desired page. The table of contents should expand itself automatically.
That’s it. As you can see, providing help inside a rich client is easy, once you do know which plug-ins are required.