| Author: | Jaap Murre |
|---|---|
| Version: | 0.1 |
| Date: | November, 2012 |
This is a JavaScript library that adds on-page guidance to a web page. After starting a ‘tour’, a series of tooltip dialogs highlights the interesting or to-be-learned parts of a page.
The contents of the tooltip dialogs (i.e., the actual guidance texts) are provided in each element in a special attribute: data-guidance. For example: <div data-guidance=’A help text’>...</div>. Arbitrary HTML may be used including images.
In case a help text is an empty string, the contents of the title attribute will be used automatically. This may be handy in case you want the title tooltip to have a double role. Note that the HTML tags will then appear unparsed in the non-guidance tooltips in the browser.
Call start() to start a tour. Tours may be stopped and then either started from the beginning by calling stop() or resumed from the last position by calling continue().
It is possible to execute certain code when a guider enters a node and when it leaves again, using the data-guidance-onenter and `data-guidance-onleave’ attributes, as follows:
data-guidance-onenter="dijit.byId('titlepane1')._setOpenAttr(true);"
data-guidance-onleave="dijit.byId('titlepane1')._setOpenAttr(false);"
This would open a title panel on entering (i.e., showing the guide on a title pane node), closing it again on leaving.
It is also possible to change the display order by providing the data-guidance-position attribute with a position, e.g.:
data-guidance-position="5"
Ordering is not absolute but relative, with nodes without data-guidance-position attributes appearing before those with an attribute (in on-page order). It is also possible, therefore, to use strings to specify an order.
It is possible to change the style of the highlighting of elements by specifying something like:
data-guidance-style="border: 1px solid #aa0; background-color:#c8ffff;"
After this element has been visited in the tour, that style will be maintained (also when moving to Previous).
Similarly, you can change the background color (only) of the tooltip dialog as follows:
data-guidance-bgcolor="#c8ffff"
Again, the color will be maintained after this. Note, that the help texts themselves can contain arbitrary HTML, including styled elements.
It is possible to define multiple tours on a single page and have the start with different buttons. To move an element into a separate tour (and remove it from the default tour), use:
data-guidance-tour="tour2"
You can use any identifying string here. Each element can be in only one tour. Start the tour with start(“tour2”). Calling continue() will always resume the last tour. The default tour (i.e., without data-guidance-tour attribute) is started by calling start() without arguments.
We assume that the the nm directory, with the file keymapper.js underneath it, resides itself at the same level as the dojoroot:
dojoroot/
dojo/
dojox/
nm/
guidance.js
guidance/_base.js
docs/
tests/
Register the nm module and require guidance as follows:
dojo.registerModulePath("nm","../../nm"); // path is relative to dojo.js file
dojo.require("nm.guidance");
It is necessary to include the proper style sheets for the chosen theme. E.g., in case of claro:
<style type="text/css">
@import "../../../dojoroot_1_7_1_source/dijit/themes/claro/claro.css";
@import "../../../dojoroot_1_7_1_source/dojo/resources/dojo.css";
</style>
Be sure to also add the style class to the body:
<body class="claro">
The Next button of the tooltip dialogs is focussed, meaning that the user can move to the next guidance text by pressing the Space bar or Esc button. With Tab, the user can move to the Previous and then Stop buttons. Shift-Tab moves in the other direction.
Note, that the element that is visited next in the tour will scroll into view when necessary.
The following code illustrates some of the options above. A more complete example can be found in the tests directory:
<head>
<title>Test On-page Guidance</title>
<style type="text/css">
@import "../../../dojoroot_1_7_1_source/dijit/themes/claro/claro.css";
@import "../../../dojoroot_1_7_1_source/dojo/resources/dojo.css";
</style>
<script type="text/javascript" djConfig="parseOnLoad:1,isDebug:1,async:0" src="../../../dojoroot_1_7_1_source/dojo/dojo.js"></script>
<script>
dojo.registerModulePath("nm","../../nm"); // path is relative to dojo.js file
dojo.require("nm.guidance");
dojo.require("dijit.TitlePane");
var guider;
dojo.addOnLoad(function()
{
guider = nm.guidance();
//guider.start(); // Use this to automatically start the tour
});
</script>
</head>
<body class="claro" style="padding:2em;">
<button data-guidance=""
title="This button starts the tour from the beginning. Notice that the title attribute has been used because the data-guidance attribute string is left empty."
onclick="guider.start();">Start Tour</button>
<button data-guidance="This button continues the tour from the last position" onclick="guider.continue();">Continue Tour</button>
<div> </div>
<div id="titlepane1"
data-guidance="Help for this 'title pane'"
data-guidance-onenter="dijit.byId('titlepane1')._setOpenAttr(true);"
data-guidance-onleave="dijit.byId('titlepane1')._setOpenAttr(false);"
data-dojo-type="dijit.TitlePane" data-dojo-props="title: 'I\'m a TitlePane', open: false">
<br /><br /><br /><br /><br />
Click arrow to close me. <br />
This pane opens when a guiders enters (i.e., is activated on this node) and should close when clicking Next. <br />
Right now, the guide is tied tot the bar and not the content, so it appears in the wrong spot.
</div>
<h1 data-guidance="Help text for the header, which may include <b>HTML</b>" style="margin-left:5em;">On-page Guidance</h1>
<p style="margin:5em;">
This page has on-page guidance based on the Dojo Toolkit. Each element that requires guidance
is given an extra attribute <code>data-guidance="My guidance test.</code>. On page load the
<code>init_guidance().start()</code> is called and it works. Or start tour later by calling
<code>start()</code> later.
</p>
<p data-guidance="Here the background color of the guider changes to blue." data-guidance-position="3"
data-guidance-bgcolor="#c8ffff" style="margin:5em;">
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
</p>
<p data-guidance="Help text for paragraph 2" data-guidance-position="2"
data-guidance-style="border: 1px solid #aa0; background-color:#c8ffff;" style="margin:5em;">
Paragraph 2, which is the second paragraph. Here, the style of the highlighted element changes to light blue.
</p>
<p data-guidance="Help text for paragraph 1, which is shown before the paragraphs above. It also has a place kitten <img src='http://placekitten.com/100/100' />"
data-guidance-position="1" style="margin:5em;">
Paragraph 1, which is actually the third paragraph.
</p>
<div data-guidance="Help text hidden element should not be shown"
data-guidance-position="5" style="margin:5em;display:none !important;">
This is a hidden paragraph, number 5, but not shown.
</div>
<p data-guidance="Help text for paragraph 4. (Hidden paragraph before this. Should have been skipped in the tour."
data-guidance-position="4" style="margin:5em;">
Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of "de Finibus Bonorum et Malorum" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, "Lorem ipsum dolor sit amet..", comes from a line in section 1.10.32. <div id= "div2">
</p>
</body>
- Disable Previous button on position 0 and Next button on end.
- Add attribute to over-ride where the tooltip will appear (e.g., data-guidance-location=’top’)