Describing and packaging context-sensitive help content
Context-sensitive help is described by associating the context id declared in
the UI code with a description and list of links to related topics or commands
in the online help. These associations are made inside an XML file located
within the plug-in that contains the topics in question. You can create any number
of XML files containing context help associations for each plug-in. The
description and links for each context id is made inside
<context> elements in the XML file. Each context element
can have an optional <description> element which is used
to describe the UI object and any number of <topic>
elements which link to the on-line documentation, as well as command links
to perform any operation for the user, e.g. open a cheat sheet.
Since 3.1, context elements can optionally override the default title used to
present the context help information in the Help view.
<contexts>
<context id="panic_button" title="Panic Button Title">
<description>This is the panic button.</description>
<command serialization="org.eclipse.ui.cheatsheets.openCheatSheet(cheatSheetId=org.eclipse.panic.button.cheatsheet)quot; label="Pushing the panic button"/>
<topic href="reference/panic_button.htm" label="Panic Button Reference"/>
</context>
...
</contexts>
Once the contexts have been described in the XML file (or files), you are ready
to refer to the context files in your plug-in manifest. Note that the context id
is not qualified.
A plug-in containing context files contributes them using the
org.eclipse.help.contexts
extension point.
<extension point="org.eclipse.help.contexts">
<contexts file="myContextHelp.xml" />
</extension>
You can reference context files from other plug-ins by including the plugin
attribute. This allows you to group all of your documentation, including
content-sensitive help, in one plug-in, and refer to it from the UI code plug-in or some other
related plug-in.
<extension point="org.eclipse.help.contexts">
<contexts file="myContextHelp.xml" plugin="com.example.helpExample" />
</extension>
When a context id is declared in an extension point the Eclipse help system will create a fully qualified
context id of the form <plug-in name>.<context id>
and use this when matching against the context
ids used in the Java source. <plug-in name> is the value of the "plugin" attribute, or if not specified the
name of the plug-in in which the org.eclipse.help.contexts extension is declared.
Context-sensitive help from multiple plug-ins
Another level of flexibility is the ability to contribute context-sensitive
help for the
same context id from different plug-ins. This is useful, for example, if
there are different sets of documentation plug-ins that may or may not be
installed in a user's configuration. This allows each documentation
plug-in to declare its contexts independently. The end user will see the
merged context-sensitive help content for all plug-ins that contributed contexts for the
widget's id.
Note that the plugin attribute must be used in the extensions if multiple plugins will
contribute to the same context. When multiple plug-ins contribute
context-sensitive help for
the same context ID, the content defined in the plug-in that declared the
context (the UI plug-in) is shown first. Additional descriptions and links
are appended in no guaranteed order.
Dynamic content
Dynamic content is available for the context help in the form of
filters on context help topic links. For
example, you may want a topic link to show up in the context help only when running
on a specific operating system.
Adding Context Help to your Java Code
See
declaring a context Id for more
information.