Context-Sensitive WebHelp

Transcript Context-Sensitive WebHelp

Context-Sensitive WebHelp
Eric Armstrong
President, Founder, Sole Employee
TreeLight Enterprises
[email protected]
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
• Print
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
[email protected]
23

Context-Sensitive WebHelp

Transcript Context-Sensitive WebHelp

Directory