# Context-Sensitive Help UA Plug-ins

Context-sensitive help UA plug-ins handle the mapping of help contexts to context-specific help content and related online documentation topics.

For projects that use the DTP help-helper, context-sensitive help plug-ins contribute:

- Eclipse context XML files, which supply the context-specific help content for each help context, and point to other help topic contributions related to the help context
- Java properties files, which define the property key-value pairs that map abstract helpKey constants to concrete help context IDs and context-specific help search expressions

Tip: The helpKey properties files are usually contributed in pairs, one each for help context IDs and help search expressions.

The following diagram shows how a dedicated context-sensitive help plug-in interacts with the DTP help-helper and the Eclipse help system at runtime, to provide dynamic context-sensitive help for a UI plug-in.

During workbench startup:

- The DTP help-helper registers helpKey properties file contributions, declared by context-sensitive help plug-ins
- The Eclipse help system registers:
  - IContext content contributions, declared by context-sensitive help plug-ins
  - Online help (TOC and topics) contributions, declared by documentation plug-ins

After the workbench is initialized, the GUI is presented, with workbench parts and controls contributed by UI plug-ins. Context-sensitive help requests are usually handled by a UI plug-in (or its delegated help event listener), for the workbench parts and UI controls that it contributes.

When the user requests context-sensitive help (for example, by pressing F1, or clicking a help icon), the following sequence occurs:

1. The UI plug-in requests a concrete help context ID from the DTP help-helper, by passing an abstract helpKey.
2. The DTP help-helper looks up the help context ID by its associated helpKey, in the helpKey properties file that was registered for the UI plug-in.
3. The DTP help-helper returns the help context ID to the UI plug-in.
4. The UI plug-in sets the concrete help context ID on its associated workbench part or UI control, and then passes that help context ID to the Eclipse help system to request the display of context-sensitive help.
5. The Eclipse help system looks up the context-specific content and related topics by help context ID, retrieves them from the context XML file that was registered for the UI plug-in, and then displays them in the Help view.
6. Upon user request (by clicking a related topic link), the Eclipse help system retrieves the help topic content contributed by a documentation plug-in and displays it in the Help view.

- Eclipse Context XML Files Extension
  Each plug-in that contributes an Eclipse context XML file must declare an extension to org.eclipse.help.contexts in its plug-in manifest (plugin.xml file).
- helpKey Properties Files Extension
  Each plug-in that contributes helpKey properties files must declare an extension to org.eclipse.datatools.help.helpKeyProperties in its plug-in manifest (plugin.xml file).
- Context-Sensitive Help Plug-in IDs
  Context-sensitive help plug-ins can be supplied as dedicated plug-ins, which point to related help topics that are contributed by other, online documentation plug-ins, but do not contribute any help topics themselves.