How to create context-sensitive help for a web-based application, based on an approach I created in 1997.

1. Developing Context-sensitive
Help for Web Applications
Scott DeLoach
Founder, ClickStart
Embedded UA consultant and trainer
Certified Instructor – Flare | Captivate | RoboHelp
scott@clickstart.net
www.clickstart.net
© 2008 ClickStart, Inc. All rights reserved.

2. Overview
How to create context-sensitive…
 external help
 embedded UA
using…
 JavaScript (JS)
 Active Server Pages (ASP)
 Asynchronous JavaScript with XMLHttpRequest (AJAX)

3. Linking an application to a help system
 Hard-coding
 Mapping with a header file
 “Auto-mapping”

4. Sample Application
Field-level Help
Page-level Help

5. CSH using JavaScript – hard-coding links
<a href="#" onClick="openHelp('thispage.htm')">Help</a>
<script>
function openHelp(page) {
helpWin = window.open(page,'helpwin','toolbar=0,location=0, 
directories=0,status=0,menubar=0,scrollbars=1,resizable=1,width=600,height=400');
setTimeout('helpWin.focus();',250);
}
</script>

6. Hard-coding links - pros and cons
Pros
 Little work for help author
 Simple solution for small applications
Cons
 A lot of work for application developer
 Doesn't scale well for large applications

7. CSH using JS – mapping page-level help
<a href="#" onClick="MyWebHelp_CSH.htm#AppPage.htm">
<img src="fieldhelp.gif" width="18" height="18" border="0"></a>
OR
<a href="#" onClick="MyWebHelp_CSH.htm#1000">
<img src="fieldhelp.gif" width="18" height="18" border="0"></a>

8. CSH using JS – mapping help links
Header (“map”) file
#define thispage 1000
#define thispage_projectnumber 1100
#define anotherpage 2000
Alias file
<Map Name="thispage" Link= "/Content/thishelppage.htm" />
<Map Name="thispage_projectnumber" Link=
"/Content/projectnumber.htm" />
<Map Name=“anotherpage" Link= "/Content/thishelppage.htm" />

9. Mapped help links – working with developers
Developer
 Usually created the IDs
Help Author
 Maps the IDs to numbers (stored in header file)
 Maps numbers to topic filenames (stored in alias file)
Both
 Share header file

10. CSH using JS – “auto-mapped” page-level help
<script>
function openCSHelp() {
helpurl = location.href;
begin=helpurl.lastIndexOf('/');
begin = begin + 1;
end=helpurl.lastIndexOf('m');
end=end + 1;
helpurl = "h_" + helpurl.substring(begin, end);
helpWin =window.open(helpurl,'CShelpwin','toolbar=0, 
location=0, directories=0,status=0,menubar=0,scrollbars=0, 
resizable=0, width=300,height=200');
setTimeout('helpWin.focus();',250);
}
</script>

11. CSH using JS - “auto-mapped” field-level help
<a href="#" onClick="openCSFieldHelp('ProjectNumber')">
<img src="fieldhelp.gif" width="18" height="18" border="0"></a>
<script>
function openCSFieldHelp(id) {
helpurl = "h_" + id + ".htm";
helpWin =window.open(helpurl,'CShelpwin','toolbar=0,location=0,directories=0, 
status=0, menubar=0,scrollbars=0, resizable=0,width=300,height=200');
setTimeout('helpWin.focus();',250);
}
</script>

12. “Auto-mapped” links – working with developers
 Help filenames must match application filenames (h_
+ pagename.htm)
 Same code for all page-level Help
 Field help requires each field to have a name

13. CSH using ASP
Field-level Help
Page-level Help

14. CSH using ASP - field-level help
JavaScript Code to Open the Help
<a href="#" onClick="openFieldHelp('ProjectNumber')">
<img src="fieldhelp.gif" width="18" height="18" border="0"></a>
<script>
function openFieldHelp(topic) {
helpWin=window.open('fieldhelp.asp?' +
topic,'helpwin','toolbar=0,location=0, 
directories=0,status=0,menubar=0,scrollbars=1,resizable=0,width=600, 
height=400');
}
</script>

15. CSH using ASP - field-level help
VBScript Code to Open the Database
Dim objConn
Set objConn = Server.CreateObject("ADODB.Connection")
objConn.Open "DRIVER={Microsoft Access Driver (*.mdb)};
DBQ=" & Server.MapPath("dbfieldhelp.mdb")
Dim objRS
Set objRS = Server.CreateObject("ADODB.Recordset")
objRS.Open "Tutorial", objConn, , , adCmdTable

16. CSH using ASP - field-level help
 "HlpText" is used to store defaults.
 "HlpTextCustom" is used to store modified help topics.

17. CSH using ASP - field-level help
Code to Pull the Field Help from the Database
Do While Not objRS.EOF
If Request.QueryString = objRS("FieldID") Then
If objRS("HlpTextCustom") <> "" Then
Response.Write "<b>"& objRS("FieldLabel") &
"</b><br> " & objRS("HlpTextCustom")
Else
Response.Write "<b>"& objRS("FieldLabel") &
"</b><br> " & objRS("HlpText")
End If
End If
objRS.MoveNext
Loop

18. CSH using ASP - working with developers
 Help filenames can have any name
 Field help requires separate help icons for fields

19. Creating context-sensitive embedded UA
 Can be created for fields or pages
 Can be created using:
 DIVs or spans
 iFrames
 AJAX
 Each context-sensitive element needs an ID
 JavaScript method: getElementById

20. Opening embedded UA - demo

21. Opening embedded UA - demo

22. Opening embedded UA - divs
Embedded UA
<div id="helpPane">UA content</div>
JavaScript Code
function toggleUA() {
if (document.getElementById('helpPane').style.display=="block") {
document.getElementById('helpPane').style.display = "none";
}
else {
document.getElementById('helpPane').style.display = "block";
} }

23. Opening embedded UA - iFrame
Embedded UA
<div id="helpPane"><iframe src="h_myApp.htm"></iframe></div>
JavaScript Code
function toggleUA() {
if (document.getElementById('helpPane').style.display=="block") {
document.getElementById('helpPane').style.display = "none";
}
else {
document.getElementById('helpPane').style.display = "block";
} }

24. Opening embedded UA - AJAX
Embedded UA
<div id="helpPane></div>
JavaScript Code
function toggleUA() {
if (document.getElementById('helpPane').style.display=="block") {
document.getElementById('helpPane').style.display = "none"; }
else {
xmlhttp.open("GET", "h_myApp.htm",true);
xmlhttp.onreadystatechange=function() {
if (xmlhttp.readyState==4) {
document.getElementById('helpPane').innerHTML = xmlhttp.responseText;
document.getElementById('helpPane').style.display = "block";
} } xmlhttp.send(null) } }

25. Opening embedded UA - AJAX
JavaScript Code to use XMLHttpRequest (IE specific)
var xmlhttp=false;
/*@cc_on @*/
/*@if (@_jscript_version >= 5)
try {
xmlhttp = new ActiveXObject("Msxml2.XMLHTTP");
} catch (e) {
try {
xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");
} catch (E) {
xmlhttp = false;
} }
@end @*/

26. www.clickstart.net
Scott DeLoach
Founder, ClickStart
Embedded UA consultant and trainer
Certified Instructor, Flare | RoboHelp | Captivate
scott@clickstart.net
404.520.0003
www.clickstart.net
Questions?