Context-Sensitive Help 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.

Generating Context-Sensitive Help

When WebHelp Responsive output is generated, the transformation process produces an XML mapping file called context-help-map.xml and copies it to the output folder of the transformation. This XML file maps an ID to a corresponding HTML page through an <appContext> element, as in the following example:

<map productID="oxy-webhelp" productVersion="1.1">
  <appContext helpID="myapp-functionid1" path="tasks/app-help1.html"/>
  <appContext helpID="myapp-functionid2" path="tasks/app-help1.html"/>
    .  .  .
</map>

The possible attributes are as follows:

helpID

A Unique ID provided by a topic from two possible sources (<resourceid> element or @id attribute):

resourceid

The <resourceid> element is mapped into the <appContext> element and can be specified in either the <topicref> within a DITA map or in a <prolog> within a DITA topic. The <resourceid> element accepts the following attributes:

appname - A name for the external application that references the topic. If this attribute is not specified, its value is considered to be empty ("").
appid - An ID used by an application to identify the topic.
id - Specifies a value that is used by a specific application to identify the topic, but this attribute is ignored if an @appid attribute is used.

Note: Multiple @appid values can be associated with a single appname value (and multiple @appname values can be associated with a single @appid value), but the values for both attributes work in combination to specify a specific ID for a specific application, and therefore each combination of values for the @appid and @appname attributes should be unique within the context of a single root map. For example, suppose that you need two different functions of an application to both open 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>

For more information about the <resourceid> element, see DITA Specifications: <resourceid>.

id

If a <resourceid> element is not declared in the DITA map or DITA topic (as described above), the @id attribute that is set on the topic root element is mapped into the <appContext> 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 and the help system will not work properly.

path

The path to a corresponding WebHelp page. This path is relative to the location of the context-help-map.xml mapping file.

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

The XML mapping file can be loaded by a PHP script on the server side. The script receives the contextId value and will look it up in the XML file.
Invoke the cshelp.html WebHelp system file and pass the contextId parameter with a specific value. The WebHelp system will automatically open the help page associated with the value of the contextId parameter.
```
cshelp.html?contextId=myDITATopic
```
Note: The contextId parameter is not case-sensitive.

Attention: Prior to version 24.1, the method was to invoke the index.html file. The system still works using this method but it has been deprecated and its functionality will be removed in a future version.

Context-Sensitive Queries

You can use the URL field in your browser to search for topics in a context-sensitive WebHelp system with the assistance of the following parameters:

contextId

The WebHelp JavaScript engine will look for this value in the context-help-map.xml mapping file and load the corresponding help page.

Note: You can use an anchor in the contextId parameter to jump to a specific section in a document. For example, contextId=topicID#anchor.

appname

You can use this parameter in conjunction with contextId to search for this value in the corresponding appname attribute value in the mapping file.

http://localhost/webhelp/cshelp.html?contextId=topicID&appname=myApplication

Tip: The webhelp.csh.disable.topicID.fallback parameter can be set true to use a topic ID fallback when resourceid information is not available when computing the mapping for context sensitive help.