developing context-sensitive help for web-based applications - scott deloach, clickstart
DESCRIPTION
How to create context-sensitive help for a web-based application, based on an approach I created in 1997.TRANSCRIPT
Developing Context-sensitive
Help for Web Applications
Scott DeLoach
Founder, ClickStart
Embedded UA consultant and trainer
Certified Instructor – Flare | Captivate | RoboHelp
www.clickstart.net
© 2008 ClickStart, Inc. All rights reserved.
Overview
How to create context-sensitive…
external help
embedded UA
using…
JavaScript (JS)
Active Server Pages (ASP)
Asynchronous JavaScript with XMLHttpRequest (AJAX)
Linking an application to a help system
Hard-coding
Mapping with a header file
“Auto-mapping”
Sample Application
Field-level Help
Page-level Help
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>
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
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>
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" />
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
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>
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>
“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
CSH using ASP
Field-level Help
Page-level Help
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>
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("\db\fieldhelp.mdb")
Dim objRS
Set objRS = Server.CreateObject("ADODB.Recordset")
objRS.Open "Tutorial", objConn, , , adCmdTable
CSH using ASP - field-level help
"HlpText" is used to store defaults.
"HlpTextCustom" is used to store modified help topics.
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
CSH using ASP - working with developers
Help filenames can have any name
Field help requires separate help icons for fields
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
Opening embedded UA - demo
Opening embedded UA - demo
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";
} }
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";
} }
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) } }
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 @*/
www.clickstart.net
Scott DeLoachFounder, ClickStart
Embedded UA consultant and trainer
Certified Instructor, Flare | RoboHelp | Captivate
404.520.0003
www.clickstart.net
Questions?