Tips for debugging active help

The code and markup that triggered our active help link looks pretty straightforward.  But what do you do if your active help link doesn't seem to work?

Test your action ahead of time

If your action implementation is fairly involved, you should invoke the action yourself with some test code inside Eclipse.  This way, you'll know that the action is error-free before invoking it from the JavaScript. 

Ensure the JavaScript is running

You can modify "liveHelp.js" (make a copy of this from the plugins/org.eclipse.help plugin and change your script statement to refer to your local copy) to include a call to the alert function as the first statement in the liveAction function:

function liveAction(pluginId, className, argument)
{
	alert("liveAction called");
	...

The alert function opens a warning dialog in the browser and can be used to verify that the liveAction was properly invoked in your HTML.  If you don't see a warning dialog when you click on your help link, then you have a problem in the HTML markup.

Debug the active help action

Once you know that the JavaScript is running, you can debug your action from inside Eclipse.  To do this, you can set a breakpoint in your help action class and start up a self-hosted Eclipse instance.  You must test your active help with the Help browser from the newly launched Eclipse instance, not from your host instance, since the JavaScript from your help HTML calls a servlet on the Eclipse help server that launched the browser.

If nothing happens after you've set up the breakpoint and clicked on the active help link, it's likely that your plug-in and active help class were not correctly specified in the JavaScript. 

Once you've managed to stop at the breakpoint in your action, you can debug the action as you would any other Java code.

Make sure your UI code is wrapped in Display.syncExec

A common runtime problem is improperly accessing UI code from the thread that invokes the active help.  If your live help action came from code that ran originally in a UI thread, it will need to be modified to handle the fact that it is running from a non-UI thread. 

public void run() {
		// Active help does not run on the UI thread, so we must use syncExec
		Display.getDefault().syncExec(new Runnable() {
							public void run() {
								//do the UI work in here;
							}
		});		
	}