Context-Sensitive WebHelp Eric Armstrong President, Founder, Sole Employee TreeLight Enterprises [email protected] 1
Context-Sensitive WebHelp Eric Armstrong President, Founder, Sole Employee TreeLight Enterprises [email protected] 1.
Jan 16, 2016
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Context-Sensitive WebHelp
Eric ArmstrongPresident, Founder, Sole Employee
TreeLight [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 targethttp://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—Requirements1. 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
http://treelight.com/dita/cs_webhelp/index.htmlWebHelp Kung Fu—Demo
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
18
showHelp.jsfunction showHelp(topicID) { var pageTitle = lookup_help_title(topicID) display_help(pageTitle) }
Launching WebHelp
(Standalone application needs equivalent code)
19
ShowHelp.jsfunction 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()}
Mapping IDs to Titles
20
• 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", \ }'
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.)
21
showHelp.jsfunction 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?
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 EmployeeTreeLight [email protected]
23
Related Documents
