Context-Sensitive WebHelp
Context-Sensitive WebHelp
Eric Armstrong
President, Founder, Sole Employee
TreeLight Enterprises eric@treelight.com
1
Contents
• Short intro to WebHelp
• How you create it
• How you do context-sensitive help
2
What is WebHelp?
• Like CHM (standard Windows help)
• HTML + JavaScript (local files or server)
• No Adobe download (only advantage over AirHelp)
3
Generating WebHelp
• XMetaL (direct)
• chm2web (http://chm2web.aklabs.com/)
– .ditamap dita-ot .chm files
– .chm chm2web webhelp files
– “Template driven”
4
XMetaL WebHelp—The Good
• Collapsible TOC
• Topic highlighting
• Index/Search
• Browse
5
Following a Link in WebHelp
<a href=" Internet_About_c.html#web_about “>
8
Same URL in a Browser
• Oops…
• No framework
9
Same Source w/Browser Address Bar
• URL = Browser_Guide.html#Following Links
10
After Following the Link
• URL = Browser_Guide.html#How the Web Works
• (JavaScript magic) … Eureka!
11
Context Sensitive Access Methods
• Method #1: JavaScript Judo
– Found on the web
– Convert application page name (pg1.jsp) to help target path_to_webhelp.html#pg1.html
• File path is necessary (directory hierarchy)
• Only works for web applications—if it works (some doubt)
• Method #2: WebHelp Kung Fu (Lookup Table)
– Pass page title in the URL (known to work) http://…yourWebHelp.html#Some Topic Title
– Look up title using topic ID (less brittle)
12
JavaScript Judo
• Map each application page to a help target http://www.idratherbewriting.com/2007/06/20/context-sensitive-help-an-easy-method-using-javascript/
<script> function showHelp() { var pagePrefix = “http://path_to_webhelp/index.htm#” var helpExt = “.html” // To convert .JSP to .HTML var pageName = window.location.pathname; pageName = pageName.substring(pageName.lastIndexOf(‘/’) + 1); var pageExt = pageName.substring(pageName.lastIndexOf(‘.’)); pageName = pagePrefix + pageName.replace(pageExt, helpExt)
}
… myWindow = window.open(pageName, “tinyWindow”, …) myWindow.focus()
<a href=”javascript:showHelp()”>…</a>
Does not work with XMetaL implementation. E.g.: http://treelight.com/dita/cs_webhelp/webhelp_out/Browser_Guide.html#Internet_About_c.html
13
WebHelp Kung Fu—Requirements
1. Naming strategy for topic IDs (scr_login, …)
2. Map topic IDs to topic titles (or filenames)
– Application code (JavaScript, for a web app)
3. Auto-generate the lookup table
– Rerun before shipping
– Ensure accurate mapping
4. Launch WebHelp appropriately
– Separate browser window (side-by-side w/app)
– No menus or toolbars
– Address bar (if users need bookmarks)
14
WebHelp Kung Fu—Demo
http://treelight.com/dita/cs_webhelp/index.html
15
Caveat
• If WebHelp isn’t running, everything good:
– WebHelp is launched
– Targeted page is displayed
• If WebHelp is running:
– Clicking a link brings help window to top (good)
– Last viewed page is displayed, not targeted page
(less than ideal)
• Desirable?
– Retains TOC as the user had it (not a server)
16
Source Page
<html>
<head>
<script src=" json_sans_eval.js
“ type="text/javascript"></script>
<script src=" help_index.js
" type="text/javascript"></script>
<script src=" showhelp.js
" type="text/javascript"></script>
</head>
…
<a href="javascript:showHelp('br_links')">
<img border="0" alt="help" src=" help_button.png
" width="18" height="18">
</a>
17
Main JavaScript Function
• Take a topic ID as an argument
• Look up the associated title (or filename)
• Launch WebHelp using that information showHelp.js
function showHelp(topicID) { var pageTitle = lookup_help_title(topicID)
display_help(pageTitle)
}
18
Launching WebHelp
ShowHelp.js
function display_help(pageTitle) { var pagePrefix = "webhelp_out/Browser_Guide.html#“ var helpURL = pagePrefix + pageTitle myWindow = window.open(helpURL, "tinyWindow",
'scrollbars=yes,menubar=no,toolbar=no,location=no,
status=no,height=600,width=900,resizable=yes') myWindow.focus()
}
(Standalone application needs equivalent code)
19
Mapping IDs to Titles
• JSON Format (JavaScript Object Notation)
• A list of comma-separated Name : Value pairs
{ "br_bookmarks" : "Bookmarks",
"br_links" : "Following Links",
}
• Defined as a string that is passed to the parser at runtime: var help_index = '{ \
"br_bookmarks" : "Bookmarks", \
"br_links" : "Following Links", \
}'
20
Processing the Lookup Table
• Included in the page at the outset
<script src=" help_index.js
“ …>
• Or read from a separate file to allow dynamic updates.
(Takes longer. AirHelp better.) showHelp.js
function lookup_help_title(topicID) { var lookupTable = jsonParse(help_index); if (topicID in lookupTable) { return lookupTable[topicID]
} alert("No help entry for index: " + topicID)
}
• Dynamic Processing for Static Info. Overkill?
21
Generating the Lookup Table
• Process a map
• Read all referenced topics
• Extract topic IDs and titles
• Generate JSON (JavaScript object)
• Ruby program, available from the RuDI source code repository. (Not yet in a download pkg) http://kenai.com/projects/rudi/sources/subversion/content/ lib/rudi/generate_webhelp_index.rb
22
Context-Sensitive WebHelp
(The End)
Eric Armstrong
President, Founder & Sole Employee
TreeLight Enterprises eric@treelight.com
23
