Context Help Editor

Context-sensitive help is a mechanism that enables linking a user interface part with a specific help topic. When the user activates the associated user interface part, the help page is displayed in the dynamic help area. The user interface and the help pages are associated with each other in two ways: a static XML file or a dynamic context provider. To associate pages statically, a context help xml file must be created. The context help editor assists in the creation of these pages.

The Definition page of the editor provides a graphical view of the xml file, separated into two columns. The one on the left is titled Context Help and displays the xml elements in a tree format along with actions to add, move and remove them. The other column provides more detailed information about the element selected in the left column and enables editing of the details.

The Source page of the editor provides a textual view of the xml file. The xml can be edited directly and changes, if valid, will be reflected on the graphical Definition page.

Adding new help contexts

Help context editor with filled fields

To add a new context, click the Add Context button. This will add a new context entry to the xml and it will be displayed in the tree on the Definition page. The new context will be selected, opening a detail section in the right column of the editor. In this detail section you can provide more detailed information about the context including:

Adding help topics and commands

Adding a context to the file will provide dynamic help with a basic description to display to the user. Typically you will want to provide additional links to related topics in the help system. To do this you must add topics and commands to the xml file.

Help context editor with filled detail fields

By clicking on the Add Topic button, you will add a new topic entry to the xml under one of the help contexts. A topic will appear to the user as a link. Once a new topic is created, you can select it to open the Topic Details section on the right column of the Definition page. In the detail section you can change the label that will be displayed to the user and the location of the file that will be linked. In most cases, the linked file will be an html page in the help system. You can use the Browse... button to search for a file to link.

In addition to topics, you may also want to add a command. A command has the same appearance to the user as a topic. However, when the link is activated, a code command is executed instead of a file being opened. Commands can be used to open preference pages and execute other actions.

Help context editor add command

Clicking the Add Command button to add a new command. You can edit the details of commands in the same way that you edit topics.

Remove, up, down Commands

There are three additional buttons on the Definition page, which enable manipulating with the items order on the context list or with deleting the items.

Help context with manipulating buttons

These buttons are:

Registering the context help file

For Eclipse to recognize the context help xml file as being a source for the dynamic help system, it must be registered via the extension point. The editor provides a way to register the context help file automatically. In the top righthand corner of the editor, there is a link called "Register this context help file". Clicking on this link will add the correct entry to the plugin.xml file.