Context-sensitive WebHelp Classic 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 Classic output is generated, the transformation process produces an XML mapping file called context-help-map.xml and copies it in 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 the id attribute that is set on the topic root element):
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. Also, starting with DITA 1.3, the id attribute was deprecated in favor of the appid attribute.
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: resourceid 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: resourceid 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 one of the WebHelp system files index.html or index_frames.html 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.
    Note: The contextId parameter is not case sensitive.
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
Tip: You can use an anchor in the contextId parameter to jump to a specific section in a document. For example, contextId=topicID#anchor.

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/index.html?contextId=topicID&appname=myApplication