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
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:
- Help Context ID: ID that is passed to the UI element to associate the help
- Description: Text that will be displayed to the user in the dynamic help to explain the basic function of the selected UI element.
- Custom Page Title: By default the dynamic help displays the name of the selected UI element as the help title, entering text here will override the default.
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.
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.
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.
These buttons are:
- Remove: Removes an item from the xml file
- Up: Moves the selected items upwards one place in the tree
- Down: Moves the selected items downwards one place in the in tree
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 org.eclipse.help.contexts
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.