How to Implement Context-Sensitive Help in ASP.NET App

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

tags).

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()
}

2. In the body of your page, call the help topic like this:

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.