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.