js_tutorial - The Inline Tutorial Framework (Powered by JQuery & Javascript)

Download Code (github) | View DemoInline Tutorial Screenshot Picture

Easily install a Javascript tutorial on any page, which allows you to provide a series of breadcrumbs to the user to teach them how to do something on a webpage.

Tested to run on JQuery 1.3.2, although other versions may work.

js_tutorial is designed so that you can provide a custom tutorial story file that describes a series of breadcrumbs, and js_tutorial will display them to the user, in the correct order.

Usage

In a nutshell, all you have to do to is make sure the tutorial.css, jquery.js and tutorial.js javascript files (or their minified equivalents) are included on your HTML page. Then you include your Tutorial Story Javascript file, which calls the JSTutorial.play function, and off you go.

There are a couple scenarios you might be including the javascripts. (1) When you know ahead of time the page will have a tutorial, in which case you can include the javascripts in <script> tags right on the HTML of the page. (2) When the user chooses to load the tutorial dynamically on the page, after the page has already been loaded.

Including the Stylesheet

Really a no-brainer, but here for completeness:

<html>
  <head>
    <!-- ... Other Head Content ... -->
    <link href="/stylesheets/tutorial.css" rel="stylesheet" type="text/css" />

    <!-- ... Other Head Content ... -->
  </head>
  <body>
    <!-- ... Page Content ... -->
  <body>
</html>

Including the Javascripts Via HTML

In the first case, you simply add the right script tags at the bottom of your page. If they aren’t at the bottom, your story file will need to totally remap your story object to define itself a JQuery $(document).ready call. However, since you really should be putting all your javascripts at the bottom of your pages anyway, we’ll just leave you with an example for the bottom of page case.

Somewhere at the bottom of your HTML page:

  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js" type="text/javascript"></script>
  <script src="/javascripts/tutorial.1.0.0.min.js" type="text/javascript"></script>
  <script src="/javascripts/my_tutorial.story.js" type="text/javascript"></script>

Dyanamically, via Javascript (after page load)

In the second case, you have a javascript file that dynamically loads the jquery.js, tutorial.js, and my_tutorial.story.js files (or whichever subset of them have already been loaded). Your script to do so will probably look like this:

  <script type="text/javascript">

    // .. code triggering dynamic loading of tutorial

    // If not done already, load stylesheet
    var f=document.createElement('link');
    f.setAttribute('type','text/css');
    f.setAttribute('rel','stylesheet');
    f.setAttribute('href', '/stylesheets/tutorial.css');
    document.head.appendChild(f);

    // 1st, load tutorial.js
    var f=document.createElement('script');
    f.setAttribute('type','text/javascript');
    f.setAttribute('src', 'http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js');
    document.body.appendChild(f);

    // WebKit fix: serialized loading, so they aren't executed out of order
    f.onload = function() {

      // 2nd, load tutorial.js
      var f=document.createElement('script');
      f.setAttribute('type','text/javascript');
      f.setAttribute('src', '/javascripts/tutorial.1.0.0.min.js');
      document.body.appendChild(f);

      // WebKit fix: serialized loading, so they aren't executed out of order
      f.onload = function() { 
        // 3rd, load my_tutorial.story.js, and optionally run some code when it's done
        var f=document.createElement('script');
        f.setAttribute('type','text/javascript');
        f.setAttribute('src', '/javascripts/my_tutorial.story.js');
        f.onload = function() { /* .. optional code to run right before tutorial starts  */ }
        document.body.appendChild(f);
      }

    }

    // .. any other code

  </script>

Example Tutorial Story Javascript File

Of course, for any of the javascript inclusions to work, you have to know how to make your own tutorial story file. And the best way we can think of to describe it to you is just by showing you an example.

var MyTutorialStory = {
  // A story is made up of descriptors, which are objects like this one (arbitrarily called "first")
  first: {
    // Define the content displayed in the dialog
    content: 'This is the html that is displayed for <em>step 1</em>.',
    // Define the target where this dialog is positioned (an actual HTML element, via JQuery)
    target: $('#steps div.step1').get(0),
    // Position that the arrow is supposed portrude from the dialog ('top', 'bottom', 'left', 'right')
    arrow: 'top', // or "targetPosition", if there's no arrow to display
    // CSS width of the dialog
    width: '250px',
    // Callback function (optional) returning the next story descriptor
    next: function() { return MyTutorialStory.second },
    // Callback function (optional), called when this step of the story is first displayed.
    callback: function() { alert("I can do crazy custom stuff because step 1 is working!"); }
  },
  second: {
    content: 'This is the html that is displayed for <em>step 2</em>.',
    target: $('#steps div.step2').get(0),
    arrow: 'right',
    width: '250px'
  }
};
// Start up the tutorial, by calling JSTutorial.play method defined in tutorial.js
JSTutorial.play(MyTutorialStory.first);

Currently, each JSTutorial story descriptor object supports the following definitions:

  • content: html content displayed in the dialog
  • target: HTML element where this dialog is positioned
  • arrow: string position that the arrow is supposed portrude from the dialog (in: ‘top’, ‘bottom’, ‘left’, ‘right’)
  • width: CSS string, width of the dialog box
  • next: (optional) Callback function returning the next story descriptor object
  • callback: (optional) Callback function, called when this step of the story is first displayed.

It’s really that easy! You can create as many story files as you need, of course.

Installation

You can simply drop the javascripts, images, and stylesheets folders onto an asset host, or into your current project. There’s no reason it has to be hosted on the same domain.

Don’t forget – you can also customize the images and stylesheets to your heart’s content.

How It Works

We’ll expand more on this later if necessary, but the code is pretty small and well commented at the current time.

Basically, a story file’s object is sent to the JSTutorial.play method, which builds the necessary tutorial dialog, and dynamically positions it on the page, next to the target element, with the arrow pointing to the middle target element.

If the current story descriptor has a next descriptor, defined, it displays a “next” button that the user can click to view the next descriptor’s help dialog.

If the user clicks the “close” button, the tutorial gets rid of the dialog.