It is possible to include the help server and system in an RCP application, or to host the help server as a standalone application. The help system is made up of a number of separate plug-ins:
org.eclipse.help.webapp
: This serves the HTML pages and provides the web API to search and navigate (needs org.eclipse.equinox.http.jetty
to run)org.eclipse.help.ui
: This provides actions/commands for the help pages and the help browser view, along with preference pagesorg.eclipse.help
: This provides the extension points for indexes and table of contentsorg.eclipse.help.base
: This provides the InfoCenter application and index searching abilityThere are of course a number of dependencies such as the core expressions that are used to provide content filtering, and the Jetty server which is used to provide the web application. When adding help to an RCP, ensure that the optional dependencies of the aforementioned plug-ins are included in order for it to work as expected.
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.
Actions have been deprecated for some time and new applications should use commands and handlers. The help system predates commands and handlers and has not been migrated to the new system. For more information about commands and handlers, see chapter 4 of Eclipse 4 Plug-in Development by Example Beginner's Guide, Packt Publishing.
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:
HELP_CONTENTS
: Used to create the Help Contents menuHELP_SEARCH
: Used to create the Search menuDYNAMIC_HELP
: Used to create the Dynamic Help menuThese 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:
MODE_WORKBENCH
: This is integrated with the Eclipse 3.x workbenchMODE_STANDALONE
: This acts as a standalone SWT windowMODE_INFOCENTER
: This acts as an InfoCenter web applicationThe 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