Edit online

Context-Sensitive Help System

Context-sensitive help systems assist users by offering relevant information about specific elements of a user interface, such as buttons or windows. This mechanism relies on a mapping between a unique ID and its associated HTML page.

Context-Sensitive Queries

Context-sensitive help is provided through the cshelp.html page:
http://localhost/webhelp/cshelp.html?contextId=topicID&appname=myApplication
Notes:
  • The contextId parameter is not case-sensitive.
  • The URL can include an anchor to jump to a page section (e.g. contextId=topicID#anchor).
Attention:
Prior to version 24.1, context-sensitive help was accessible via index.html. This method still works but is deprecated and will be removed in a future release.
Use the following parameters in the URL:
contextId
Used by the WebHelp JavaScript engine to open the corresponding help page. Its value comes from either:
<resourceid> (see DITA Specifications: <resourceid> for more details)
Specified in the DITA map <topicref> or in the topic <prolog> using the following attributes (ordered by priority):
  1. @appid - ID used by an application to identify the topic.
  2. @id - ID used by a specific application to identify the topic, ignored if @appid is present.
Note:
Multiple @appid values can share a single @appname, and vice versa. However, each @appid/@appname combination must be unique within the context of a single root map, as it identifies a specific application ID. For example, two different functions of an application can point to the same WebHelp page.

Example: The <resourceid> Element Specified in a DITA Map

The <resourceid> element can be specified in a <topicmeta> element within a <topicref>.
<map title="App Help">
  <topicref href="app-help1.dita" type="task">
     <topicmeta>
       <resourceid appname="myapp" appid="functionid1"/>
       <resourceid appname="myapp" appid="functionid2"/>
     </topicmeta>
  </topicref>
</map>

Example: The <resourceid> Element Specified in a DITA Topic

The <resourceid> element can be specified in a <prolog> element within a DITA topic.
<task id="app-help1">
  <title>My App Help</title>
  <prolog>
    <resourceid appname="myapp" appid="functionid1"/>
    <resourceid appname="myapp" appid="functionid2"/>
  </prolog>
...
</task>
@id
Specified in the topic root element, used if no <resourceid> is declared (in both DITA map and topic).
Important:
Ensure these IDs are unique within the entire DITA project. Duplicate IDs will trigger warning messages and the help system will not work properly.
Note:
The webhelp.csh.disable.topicID.fallback parameter can be set to true to disable the topic @id fallback when resourceid information is unavailable when computing context-sensitive help mapping.
appname (optional)
Used in combination with contextId to match the corresponding appname. Its value comes from the @appname attribute of the <resourceid> element and is empty ("") if unspecified.

Generating Context-Sensitive WebHelp

To simplify the integration of WebHelp Responsive into an application, the context-help-map.xml file is generated in the output folder. This file maps IDs to HTML pages using <appContext> elements, as shown below:
<map productID="oxy-webhelp" productVersion="1.1">
  <appContext helpID="myapp-functionid1" path="tasks/app-help1.html"/>
  <appContext appname="myapp" helpID="myapp-functionid2" path="tasks/app-help1.html"/>
  ...
</map>
The <appContext> element contains the following attributes:
@helpID
A Unique ID that identifies the topic based on the <resourceid> element or the @id attribute (as described above).
@appname (optional)
A name for the external application that references the topic from the @appname attribute of the <resourceid> element (as described above).
@path
The path to the corresponding HTML page, relative to the location of the context-help-map.xml mapping file.