Adding context sensitive Help to your Plug-in

For my Code generation plug-in I wanted to add some context sensitive help. Looking for any hints I only found a quick description at Macrobug’s that dates back in autumn 2007 when Eclipse 3.3 (Europa) was the current platform. Following these steps I could not produce any meaningful results. Therefore I figured it out on my own and present my solution here for anyone interested.

To reduce the the problem to its most simplest I created a new plug-in to test this out: New->Other->Plug-in-Project. Fill in the required values with some sensible data. On the third page select the „Plug-in with multi-page editor“. Then you can hit finish since all we need is a wizard with one page where we can call the context sensitive help.
In the project create a new folder and name it „html“. Create some html files in this folder (ie. help1.htm,help2.htm,…) that contain the contents of your context help. Then create an XML file under your project root (ie. contextHelp.xml) and add the contexts to it:

Note the id „firsthelp“. The href points to your corresponding html file with a relative path. You can add several topic elements. Now you have to make your context sensitive known in the plug-in through the extension point org.eclipse.help.contexts. To do that add the following lines to the plugin.xml:

The file has the path to your XML file you just defined. Note that the plugin attribute denotes this plug-in. It can define some other plug-in if your XML context help file is located in another bundle/plug-in.
What we have done until now is generating some artefacts that are not needed – yet. So we have to tie up all the loose ends. In effect this is done with essentially one line of code. But to understand how all this works let’s take a closer look on how the context sensitive help works.
The context is defined by a unique ID the context-ID. In your wizard this context-ID is set as a data attribute on the widget of the shell. To understand why this is important lets take a look at the suggested solution by Macrobugs:

PlatformUI.getWorkbench().getHelpSystem.displayHelp(context-ID);

What happens here is that the help context is created with your supplied context-ID and afterwards a second time with the context-ID defined in the shell that overrides your context. Your call stems from the direct call in the method performHelp, the second is executed based on the registered event listener. For all more interested in the details are referred to the inner class WorkbenchHelpListener in org.eclipse.ui.internal.help.WorkbenchHelp and there have a look at the method helpRequested(Event).
With that said all we have to is supply the widget with our context-ID. For that we override the method performHelp in our WizardPage class:

/**
 * Set the right help key for the context sensitive help
 */
public void performHelp() {
	// (WorkbenchHelpSystem.HELP_KEY = "org.eclipse.ui.help"
	getShell().setData(WorkbenchHelpSystem.HELP_KEY, "ch.sahits.tutorial.help.firsthelp");
}

The HELP_KEY is a constant in an internal class. This will generate you a warning for discouraged access, alternatively you can use the value of the constant: „org.eclipse.ui.help“. The important part is the second argument of the setData method, the value. This is your context-ID. This context-ID is put together from the plug-in ID of your plug-in where you defined your extension (in our case the very same plug-in) and the id of the context divided by a point.
An example plug-in that followed basically the same steps described here can be obtained.