Adding Interactive User Help with Intro.js

The other day I stumbled across this cool little JavaScript file called Intro.js that makes it really easy to provide user help in an interactive tutorial way.  I thought it would be a really cool thing to implement into some of my more complicated dashboards as opposed to the current technique of using tooltips or hoping that a user clicks on a wiki link to read some tomes of documentation.  Using this function, we can easily add some interactivity to the help and make it engaging for the users.

Installing the Script
The first thing you have to do is download the script (and it’s accompanying CSS file) and put it locally on your web server.  It comes with the full code version of Intro.js as well as instrojs.css.  Personally, I prefer to deploy the /minified/Intro.min.js and introjs.min.css.  The difference just saves you a couple of kilobytes of download for your users, which sometimes can matter (but probably not in this case).

I like to create a folder in my plugins directory and just drop the files in there.  We aren’t changing any MicroStrategy files (so this technically isn’t a plugin), but it keeps external files in a single, neat place and hopefully makes administration easier later.

Helping Your Dashboard
Maybe there’s a better plugin free way, but to load this in a document, I had to use some jQuery.

First, create an HTML Container and add the code to import the Intro.js library:

<script src="../plugins/javascript/intro.min.js"></script>

Next, we have to include the CSS file, and the only way I could get that to work was with jQuery:

$('head').append('<link href="../plugins/jquery/javascript/introjs.min.css" rel="stylesheet">');

We then have to add HTML attribute tags to each piece that we want to call out.  You’ll need to use your Chrome/Firefox Inspect tool to get the IDs or Classes.

Just add data-intro=”Your message” and data-step=”x” to each item.

I’m using this sample dashboard from tutorial:

And adding 3 items of help:

$('iframe').first().attr('data-intro', 'This is a map.');
$('iframe').attr('data-step', '1');
$('#W25').attr('data-intro', 'These are some line graphs.');
$('#W25').attr('data-step', '2');
$('.W28').attr('data-intro', 'This is the title box.  It tells you things.');
$('.W28').attr('data-step', '3');

Finally, you have to add a button that will start the show.  I added a little “help” link in the top right corner by adding this code to an HTML Container with the start() function:

<a onclick="javascript:introJs().start();">help!</a>

So, that works (kinda) and you can navigate through the items of the tutorial.  But as you can see, the box that should be calling out the content is all but covering it up.  I tried all kinds of things with all kinds of objects and couldn’t get it to work.  Despite posts like these, I’m not a great web hacker, so hopefully some super cool reader will come along and figure out why this isn’t working like in the Intro.js demos.  I’m sure the community (and me) will be forever grateful.

Sorry for the anti-climatic let down, but I messed with this for too long not to post something about it, so there you go.

Full Code:

<script src="../plugins/javascript/intro.min.js"></script>
<script src="../plugins/javascript/jquery.min.js"></script>
<script>
$(document).ready(function() {
$('head').append('<link href="../plugins/jquery/javascript/introjs.min.css" rel="stylesheet">');
$('iframe').first()
.attr('data-intro', 'this is a map');
$('iframe').attr('data-step', '1');
$('#W25').attr('data-intro', 'these are some line graphs.  woo');
$('#W25').attr('data-step', '2');
$('.W28').attr('data-intro', 'i hope this works');
$('.W28').attr('data-step', '3');
});
</script>
<a onclick="javascript:introJs().start();">help!</a>