Context-Sensitive WebHelp System

Context-sensitive help systems assist users by providing specific informational topics for certain components of a user interface, such as a button or window. This mechanism works based on mappings between a unique ID defined in the topic and a corresponding HTML page.

When WebHelp output is generated by Oxygen XML Editor, the transformation process produces an XML mapping file called context-help-map.xml and copies it in the output folder. This XML file maps an ID to a corresponding HTML page like:

<map productID="oxy-webhelp" productVersion="1.1">
  <appContext helpID="annotations-view" path="topics/annotations-view.html"/>
  <appContext helpID="button-editor" path="concepts/button-editor.html"/>
    .  .  .
</map>

where:

helpID - unique ID provided by a topic from two possible sources:
- the resourceid element set to it in the prolog section:
```
<prolog>
    <resourceid id="context-sensitive-help-system"/>
</prolog>
```
  Note: If you need different parts of the application (for instance, dialogs, views, or editing modes) to open the same contextual help topic, all of the context ID values should be included in the same DITA topic file. For example, if you need both a dialog box and a view to open the same WebHelp page, you can assign different resource ID in the same DTIA topic.
```
<prolog>
  <resourceid id="dialog1"/>
  <resourceid id="view1"/>
</prolog>
```

- the id attribute set on the topic root element
Important: You should ensure that these defined IDs are unique in the context of the entire DITA project. If the IDs are not unique, the transformation scenario will display warning messages in the transformation console output. In this case the help system will not work properly.
path - path to a corresponding WebHelp page. This path is relative to the location of the context-help-map.xml mapping file.
productID - ID of the product for which you are writing documentation. Applicable only if you are using WebHelp with Feedback transformations.
productVersion - version of the product for which you are writing documentation. Applicable only if you are using WebHelp with Feedback transformations.

There are two ways of implementing context-sensitive help in your application:

The XML mapping file can be loaded by a PHP script on the server side. The script receives the context ID value and will look it up in the XML file.
Invoke one of the WebHelp system files index.html or index_frames.html and pass them the contextId parameter with a specific value. The WebHelp system will automatically open the help page associated with the value of the contextId parameter.

The following example will open a frameless version of the WebHelp system showing the page associated with the id dialog1ID:

index.html?contextId=dialog1ID

The following example will open a frameset version of the WebHelp system showing the page associated with the id view1ID:

index_frames.html?contextId=view1ID