The org.eclipse.help.ui bundle is needed to integrate into the Eclipse 3 workbench. For Eclipse 3.x RCP applications, it should be added.

The ApplicationActionBarAdvisor is used to add workspace-wide menu additions, and this is the best place to add the Eclipse 3.x RCP help. When running in a hosted IDE mode, this function is performed by the workbench, which adds the actions programmatically.

The org.eclipse.ui.actions.ActionFactory is used to create instances of standard platform actions, such as copy/paste, undo, and so on. It can also be used to create the help menu actions. There are three of them, which are used for different purposes:

These actions are created in the makeActions method and then added to the menu items with fillMenuBar. The code to add the Help menu to an Eclipse 3.x RCP application is as follows:

public class ApplicationActionBarAdvisor extends ActionBarAdvisor{
  private IWorkbenchAction helpContents;
  private IWorkbenchAction helpSearch;
  private IWorkbenchAction helpDynamic;
  public ApplicationActionBarAdvisor(IActionBarConfigurer abc) {
    super(abc);
  }
  protected void makeActions(IWorkbenchWindow window) {
    helpContents = ActionFactory.HELP_CONTENTS.create(window);
    helpSearch = ActionFactory.HELP_SEARCH.create(window);
    helpDynamic = ActionFactory.DYNAMIC_HELP.create(window);
  }
  protected void fillMenuBar(IMenuManager menuBar) {
    MenuManager help = new MenuManager("Help", "help");
    help.add(helpContents);
    help.add(helpSearch);
    help.add(helpDynamic);
    menuBar.add(help);
  }
}

The ApplicationBarAdvisor class is typically hooked into the application at start-up time:

public class Application implements IApplication {
  public Object start(IApplicationContext ctx) throws Exception {
    Display display = PlatformUI.createDisplay();
    PlatformUI.createAndRunWorkbench(display,
      new ApplicationWorkbenchAdvisor());
    display.dispose();
  }
}

When the application starts up, the Help menu will be added, along with the Display Help, Search, and Dynamic Help menus.

For Eclipse 4.x RCP applications, only the org.eclipse.help.base and org.eclipse.help.webapp dependencies are required (although there may be restrictions and warnings shown for the base plug-in). The reason for this is the Eclipse 3.x help system—particularly the dynamic help—is tightly integrated with the Eclipse 3.x UI components.

Since there is limited Eclipse 4.x support for dynamic help and the integrated search view, it is necessary to create a menu and handler in E4 explicitly for the Help menu, as follows:

The handler class can use BaseHelpSystem to display the help page in an external browser. There are three modes that the help system can be launched in:

The only one that works with Eclipse 4.x RCP is MODE_INFOCENTER; so this needs to be set on the base mode before launching the help option.

The E4 command will look like the following:

@SuppressWarnings("restriction")
public class HelpCommand {
  @Execute
  public void execute() {
    BaseHelpSystem.setMode(BaseHelpSystem.MODE_INFOCENTER);
    BaseHelpSystem.getHelpDisplay().displayHelp(true);
  }
}

Ensure that the Eclipse 4.x RCP product has the dependencies listed previously, as well as the org.eclipse.equinox.http.jetty bundle, along with optional dependencies. Now when the Help menu is chosen, the help page will be shown in an external browser.

To add search support, the displaySearch method can be used, possibly triggered by the selection that the user has made, or through an interactive dialog. One possible implementation would be as follows:

@SuppressWarnings("restriction")
public class SearchCommand {
  @Execute
  public void execute() throws UnsupportedEncodingException {
    BaseHelpSystem.setMode(BaseHelpSystem.MODE_INFOCENTER);
    InputDialog dialog = new InputDialog(null, "Search",
      "What do you want to search for?", null, null);
    if (Window.OK == dialog.open()) {
      String searchString = URLEncoder.encode(
       dialog.getValue(), "UTF-8");
      BaseHelpSystem.getHelpDisplay().displaySearch(
       "searchWord=" + searchString, "", true);
    }
  }
}

The displaySearch method allows arguments to be added to the search URL. This includes searchWord and maxHits. Since this is passed through to the browser directly, the searchWord should be validated and URI encoded; in other words, replacing non-ASCII characters with % values, as well as for control characters and characters requiring special treatment such as & and +.

Context-sensitive help is more difficult to implement in an E4 application. There are defined contextId names associated with views in Eclipse (such as org.eclipse.jdt.ui.members_view_context) that have a specific page associated with them. In a 3.x application, these contexts are associated with the view implementation themselves, and the help system wires up the content automatically.

To programmatically display help associated with a context from a given key, the following needs to be done:

@SuppressWarnings("restriction")
public class ShowContextHelpCommand {
  @Execute
  public void execute() {
    BaseHelpSystem.setMode(BaseHelpSystem.MODE_INFOCENTER);
    // obtain from UI in an appropriate means
    String helpContext="org.eclipse.jdt.ui.members_view_context";
    IContext context = HelpSystem.getContext(helpContext);
    if (context == null) {
      String message = "Cannot find help for context " + context;
      ErrorDialog.openError(null, "Cannot find help", message,
       new Status(Status.ERROR, "", message));
    } else {
      IHelpResource[] topics = context.getRelatedTopics();
      if (topics.length == 0) {
        String message = "No help topics for context " + context;
        ErrorDialog.openError(null, "Cannot find help", message,
         new Status(Status.ERROR, "", message));
      } else {
        // Display first topic; add UI if multiple are returned
        BaseHelpSystem.getHelpDisplay().displayHelp(context,
         context.getRelatedTopics()[0], true);
      }
    }
  }
}

The means that acquiring the help context from the given UI will be specific to how the Eclipse 4.x RCP is implemented. It could be stored as a context variable for example.

The InfoCenter application can be launched from a standalone Eclipse installation. The org.eclipse.help.base plug-in provides an application that can be launched via the eclipse executable.

To launch a headless Eclipse instance with the InfoCenter, run the following from a command line:

$ eclipse -nosplash 
 -application org.eclipse.help.base.infocenterApplication
 -vmargs -Dserver_port=5555

The help center will start and run on the port specified in the -vmargs -Dserver_port command-line option. If the port is not specified, it will start on a random port, which makes it more difficult to determine where the server is running.

Navigating to the root page will result in a "file not found" error:

http://localhost:5555/

Instead, navigate to /help/index.jsp:

http://localhost:5555/help/index.jsp