Context-Sensitive Help -- An Easy Method Using Javascript

by Tom Johnson on Jun 20, 2007
categories: technical-writing

Context-sensitive help is usually perceived as being tedious or difficult to implement. However, if you're writing help for a web application, this little javascript trick makes delivering context-sensitive help easy. Using this method, the developer doesn't have to manually configure any of the URLs, and you as a tech writer have only a minimal amount of work as well. Each page in the application calls the right help topic for the right page. After seeing how easy it is to deliver context-sensitive help this way, I would never use any other method.

Conceptual Explanation

While easy to implement, it's conceptually tricky to explain. Just so you don't miss anything, here's the concept of how it works. Each page in the application has a help button with the exact same code. When a user clicks the help button, the help button calls a javascript that says something like this:

1. What is the name of the current page?
2. OK, great, now change the extension of this page name to .htm.
3. Call this exact same page from the help folder.

It does not matter what tool you are using for this method, as long as the application is a Web application (rather than a Winform application).

Writer's Role

Writers must follow these steps to deliver the context-sensitive help:

1.  If you're using a tool like RoboHelp or Flare (or any other tool, for that matter), match the help topic's file names with the application page names that you're associating the help topic with. For example, if the application page is called contact.aspx (look in the Web address to see the name), then you would rename your help topic's file name contact.htm. If the application page is named config.aspx, then rename the help topic's file name corresponding to this page config.htm.
2. Remove each of your help files from any distinct subfolders. You can't have some files inside folder A, some files inside folder B, others inside folder C, etc. All the files must be within the same folder.
3. Let the developer know the path and folder of the published files.

Developer's Role

1. In the following javascript code, change the path in red to match the path of the published help folder, and insert this javascript into the header of each page (between the <header> tags).
   <script>
   function showHelp(){
   //this is the name of the domain or the root url you want for the help link
   var pagePrefix = "http://samplewebpath/acmeapplication/webhelp/index.htm#"
   //this is the help extension that will replace whatever exists on the current page
   var helpExtension = ".htm"
   //this gets the current full path to the page
   var pageName = window.location.pathname;
   //this returns just the page name and its extension
   pageName = pageName.substring(pageName.lastIndexOf('/') + 1);
   //this identifies just the page extension of the current page
   var pageExtension = pageName.substring(pageName.lastIndexOf('.'));
   //this replaces the current page name extension with the help extension
   pageName = pagePrefix + pageName.replace(pageExtension, helpExtension)
   //    this shows you the link that will be opened
   //alert(pageName);
   //this is the popup script for the new window
   myWindow = window.open(pageName, "tinyWindow", 'scrollbars=yes,menubar=no,height=600,width=600,resizable=yes,toolbar=no,location=no,status=no')
   //this assures the window will come to the front of the current page
   myWindow.focus()
   }
   </script>
2. In the body of your page, call the help topic like this:<a href="javascript:showHelp()" mce_href="javascript:showHelp()"><img src="http://samplewebpath/acmeapplication/help.gif" border="0" width="16" height="15"></a>

Obviously you need to replace the path in red with the path of your actual help button file.

That's it. Now when the user clicks the help button, the page with the same file name in your help files will appear.

Externally Referencing the Javascript File

You can reference the javascript externally, rather than pasting the same code in each page's header. To do that, rather than inserting that long script into the header of each page, add this instead:

<script src="http://samplewebpath/acmeapplication/showhelp.js"> </script>

Open Notepad and insert the script, but remove the <script> tags from the beginning and end. Save the file with a .js extension.

Code the help button the same way as before.

Hiding the Table of Contents

Here's a little trick I learned a while ago with RoboHelp.

What's the difference between these two web paths?

• http://samplewebpath/acmeapplication/webhelp/index.htm#contact.htm
• http://samplewebpath/acmeapplication/webhelp/contact.htm

The first calls the topic Contact and also shows the navigation pane (table of contents).

The second shows the topic Contact without the navigation pane.

I like the navigation pane to show, so that's why in the javascript code above, I wrote it like this:

    var pagePrefix = "http://samplewebpath/acmeapplication/webhelp/index.htm#"

If you don't want the navigation pane to show, you would write it like this:
    var pagePrefix = "http://samplewebpath/acmeapplication/webhelp/"

Note: You must have a topic in your help file that has the file name index.htm (even if it's a blank file). If you don't (if it's something like home.htm), you would use home.htm instead of index.htm in the javascript call.

Changing "Show" to "Show Table of Contents"

In RoboHelp, if you hide the table of contents, you're left with a little link that says (quite nebulously) "show." Show what? Where? To whom?

You can change this Show text. I don't have RoboHelp open and in front of me, but if I remember correctly, go to File > Project Settings. Click the Advanced button. Click the LNG tab. Scroll until you see show=show. Select that and click the Edit button. Customize the text after the equals sign, like this: show=Show Table of Contents.

Credits

Special thanks to Pam Treme who showed me the context-sensitive help trick. And also special thanks to my sister for creating the Javascript code.