Providing help topics relevant to current usage scenarios is a demanding requirement in today’s enterprise web applications. It is generally called as context sensitive help. Those help systems should automatically navigate to relevant help topics in help windows according to current business process, current web page, or currently focused component in those pages.
There are similar requirements in our current web project. It should basically provide help for a focused component in a web page if there exists any available help topic for that component. If there isn’t any for that component, then it should automatically navigate to the current web page’s help section or business process’es one.
We implemented above requirements employing javascript, IE’s builting onHelp event handler, and a simple Ajax functionality to retrieve available tooltip messages from serverside without refreshing whole web page.
When someone presses F1, our help window should be opened instead of Microsoft IE’s builting help window. It’s currently achievable easily with implementing onHelp event handler in body html element as below, for example;
<BODY onHelp="openHelp(); return false"...> ... </BODY>
In openHelp method we open a new browser window, displaying related help topic:
function openHelp() {
helpUrl = 'help.html';
helpUrl += '#' + getPageHelpContextID();
if(document.activeElement && (document.activeElement.id.length > 0))
{
helpUrl += ':' + document.activeElement.id;
}
helpWin = window.open(helpUrl,'Help','toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=1,resizable=1,width=600,height=700');
setTimeout('helpWin.focus();',250);
}
function getPageHelpContextID() {
var pageCtxObj = document.getElementById('form1:pageCtxId');
if(pageCtxObj) {
return pageCtxObj.value;
} else {
return document.forms[0].id;
}
}
It first gets current page’s help context id, which is provided via a hidden html input element. This value must be unique accross the application’s help context. Page’s form id, if it is unique enough, could also be used as help context id. This page help context id is appended to the end of helpUrl. It then looks at active element in current html document. If there exist a focused (active) html component in current document and if it has an html id attribute, then that id is also appended to the end of helpUrl. We can easily focus on any component in a web page navigating via TAB key. Finally, a new window is opened calling window.open() with giving helpURL as input parameter into it.
The above section tries to explain how to enable context sensitive help mechanism in the web application. The other side of the coin is to develop help content and to keep it syncronized with web application’s page and component structure.
One of the most important points is to use same identifiers, defined inside web pages, accross the help content as those pages’ and their components’ help section ids. Basically those component ids are used as anchor names in help pages. Therefore, a full coordination between software developers and help content providers must exists during the development life cycle.