JavaScript-Based Context Sensitive Help

This topic explains how to configure your browser-based Help system to respond to context-sensitive Help requests from a software application.

Overview

If you are deploying a browser-based Help system in conjunction with a software application, you can configure your main HTML Help file to display a specific target Help file when so requested by a calling software application.

Note: The following JavaScript functions do not depend technically on anything inside your DITA source files or anything generated by the DITA Open Toolkit. They are generic functions that support generic HTML.

Single-pane Browser Help Systems

In some situations, you may not need to deploy a fancy, multiframe HTML Help solution to support a software application. In these situations, you can add a few lines of JavaScript to the beginning of your main Help file to process incoming hyperlink calls that target a particular HTML Help file.

For example, if my software application needed to display a particular Help screen (targetHelpTopic.html), I could build a hyperlink that would call the main Help file (1file.html) and ask it to display my target Help topic.

Here's the HTML hyperlink call.

<a href="1file.html?targetHelpTopic.html">link</a>

Here's the JavaScript to put at in your main Help file. 

<HTML>
<!-- One-pane Browser Help System 1file.html -->
<body>
<script language="javascript">
targetTopic = window.location.search.substring(1);
window.location.href=targetTopic
</script>
</body>
</html>

When the main Help file (1file.html) receives the HTML hyperlink call <a href="1file.html?targetHelpTopic.html">link</a>, it identifies any text that follows the question mark (?) as one or more arguments being passed to it. In this example, the script identifies targetHelpTopic.html as that argument and makes that HTML file name the current topic to be displayed in the browser.

Note: This setup works well for captive or embedded Help systems with restrictive or highly predictable calling procedures. If a user or an application calls the main Help file without specifying a target topic, the main Help file will generate an Error 404 "File not found".

Multiframe Browser Help Systems

Many browser-based Help systems use multiple frames to provide the customer with topic navigation, search, indexing, and other basic amenities. To get a multiframe Help system to respond to the same context-sensitive hyperlink call is a bit more complicated because of some restrictions in how HTML frames and JavaScript interact.

Here are the elements of our little example.

Figure 1. JavaScript Elements

Elements Description

Software application

Any software application that can generate HTTP calls to a browser will work. For the sake of simplicity, I use an HTML document that contains one hypertext link.

<html>
<a href="dhsc_help.html?target.html" target=_blank>
Call the help system file and pass it an argument
(the name of the target help topic).</a>
</html>

Hyperlink

The software application passes two arguments to the Help browser:


  • Main HTML Help file name (dhsc_help.html)
  • Target Help file name to be displayed (target.html) in the main Help window.

Preserving the question mark (?) between the name of the main Help file name and the target Help topic file name is critical. Your browser uses this question mark to delimit the name of the target Help topic (target.html) from the name of the main Help file (dhsc_help.html).

Main Help file

The main Help file here contains little more than a call to a JavaScript library file that performs all the real work.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>DHSC CS Help Demo</title>
  <!--Insert cshelp.js library -->
  <script language="Javascript" src="cshelp.js">/script>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<script language="javascript">
insertFrameset()
</script>
</html>

cshelp.js

The cshelp.js library contains only one JavaScript function named insertFrameset. 

function insertFrameset ()
{
defaultTopic = "default.html";
targetTopic = window.location.search.substring(1);
if (targetTopic=="")
	{
	target_contentsframe=defaultTopic
	}
else
	{
	target_contentsframe=targetTopic
	}

document.write('<FRAMESET cols="20%, 80%">');
document.write('<FRAME src="nav.html" name="navframe">');
document.write('<FRAME src="'+target_contentsframe+'" name="contentframe">');
document.write('</FRAMESET>');
}

The variable targetTopic points to the name of the target topic (target.html) embedded in the hyperlink call. If the JavaScript function receives no argument from the hyperlink that calls it, it uses the name of the HTML topic declared as defaultTopic. The final lines of the script build the frameset calls that specify frame dimensions and contents (HTML files).

Figure 2. Sample Context Sensitive Help

Summary

These JavaScript functions support small-to-medium Help systems in any language because they place the entire burden of constructing and managing context-sensitive hypertext links on the calling application. With larger Help systems or with distributed Help systems, this overloading becomes risky or impossible.

Stan Doherty

Individual

OASIS DITA Technical Committee

OASIS DITA Help Subcommittee

Parent topic: Developing Custom DITA-based Help Systems