Developing Context-sensitive Help for Web-based Applications - Scott DeLoach, ClickStart

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.

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

scott@clickstart.net

404.520.0003

www.clickstart.net

Questions?