Context-Sensitive WebHelp - TreeLight

duckexcellentInternet και Εφαρμογές Web

5 Φεβ 2013 (πριν από 4 χρόνια και 9 μήνες)

216 εμφανίσεις

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


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

http://treelight.com/dita/cs_webhelp/index.html

WebHelp 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.js

function
showHelp
(
topicID
) {


var

pageTitle

=

lookup_help_title
(
topicID
)


display_help
(
pageTitle
)

}


Launching WebHelp

(Standalone application needs equivalent code)

19

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
()

}


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.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?

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