Contents


Add interactive documentation to your JavaScript apps with Intro.js

Give guided tours of web application features the modern, dynamic way

Comments

Users who want to get up to speed quickly with a new web app — or with new features in an app they already use — typically aren't interested in reading long documents or guides. Product demos do a better job than static documents of holding users' attention while introducing and illustrating application functionality. Guided tours, especially, are effective because they explain and demonstrate product features while the user is working within the application.

The Intro.js library takes an innovative, interactive approach to documenting JavaScript applications. The library provides the required JavaScript and Cascading Style Sheets (CSS) files for creating step-by-step tours that walk users through a web app's functionality and features. Using Intro.js, you can integrate on-the-fly information into your apps that users can view while navigating in the app environment. The library integrates with AngularJS and Node.js to enable you to add instructional information from within your development environment. UI designers and JavaScript developers can both take advantage of Intro.js functionality and resources to enhance the value of their applications in a simple, modern, and dynamic way.

Intro.js functionality is easy to implement in any website UI. The library is free of charge, open source, and compatible with the latest versions of Internet Explorer, Chrome, and Firefox. This tutorial shows you the main Intro.js features and provides a step-by-step example of implementing a guided tour.

Intro.js navigation

Intro.js implements these general navigation features:

  • Tour launch: The Intro.js library offers some sample buttons that you can use to define tour initialization. You can also design your own button (example: Screenshot of an example launch-tour icon) for calling the user's attention to the start of the tour.
  • Tour steps: You must specify the steps that users will navigate through until they complete the tour. You specify the steps through a set of HTML elements in the tour files, as you'll see in detail later in this tutorial. By default, the Intro.js library specifies navigation buttons labeled Prev (short for Previous) and Next: Screenshot of Prev  and Next navigation buttons
  • Tour departure or end: On every step of the tour, Intro.js offers an option for the user to skip the remaining steps. Users can click a button — by default, labeled End tour — to leave the tour: Screenshot of the End tour button. And when the user reaches the last step of the tour, the library implements a button labeled Done (Screenshot of  the Done button), which replaces the End tour button in this final step. Clicking the Done button completes the tour.

Next, we'll show you what the tour in our sample application looks like.

A basic tour with Intro.js

Our sample application prototype consists of a website written in JavaScript using Node.js and AngularJS. My Travel App helps travelers to manage their trips. Here's a look at the app's initial page:

Screenshot of the My Travel App home page
Screenshot of the My Travel App home page

My Travel App has a menu called Travellers Information for managing travelers, groups, and languages:

Screenshot of the Travellers Information Menu
Screenshot of the Travellers Information Menu

We created a new Launch Tour menu for running the three guided tours for My Travel App users — Getting Started, Navigate My Travel App, and Manage Travellers:

Screenshot of Getting Started, Navigate My Travel App, and                 Manage Travellers tours
Screenshot of Getting Started, Navigate My Travel App, and Manage Travellers tours

For example purposes, we've implemented only the Manage Travellers guided tour. (The Getting Started and Navigate My Travel App selections are placeholders only.) The Manage Travellers tour documents each step that users can take to manage their travelers, groups, and languages via the Travellers Information menu.

To give you a live demo of the tour functionality, we deployed My Travel App to IBM Bluemix, following the steps described in "Deploy a 'Hello World' webpage to Bluemix" to get started and then using our existing My Travel App project code.

Creating the Manage Travellers tour

Now we'll take you through the steps for using the Intro.js library to create the Manage Travellers guided tour in My Travel App. You can also follow along in our Creating the tour video demo.

Add the Intro.js library to your project

Because the sample application uses Node.js and bower components, you can obtain the Intro.js library locally by installing it through the bower installer:

bower install intro.js

You can also add the Intro.js library to the bower.json package by including it in the dependencies section:

"dependencies": {
...
"angular-intro.js": "~1.1.3",
...
}

See the Intro.js project page on GitHub for more information on how to download and install Intro.js.

Update your HTML to add the Intro.js library to your website

Here's how to include Intro.js code in an HTML page:

<li>
 <a role="menuitem" tabindex="-1" id="travellersTourController"
   ng-controller="TravellersTourController"
   ng-click="startTravellersTour()">
 <i class="header-nav-icon" ng-include="'/static/icon/travel_icon.svg'"></i>
   <span translate="NAV_TOUR_MANAGE_TRAVELLERS"></span>
 </a>

The values for id, ng-controller, and ng-click in the preceding code are specific to our implementation. We'll explain them in the following text.

Create the controller file

The sample application uses AngularJS and a new controller —TravellersTourController— that we created to store all the code related to the Intro.js library. The controller code:

  1. Declares the use of the Intro.js library
  2. Starts Intro.js
  3. Defines the steps displayed on the guided tour
  4. Ends the tour

See Download to get the code for TravellersTourController.

Define the Intro.js variable

Before defining the tour steps, the controller code defines a new variable, intro:

var intro = Intro.js();

Now functions and events in the controller can reference the Intro.js library with the intro variable.

Define the tour steps

To specify the tour steps, you create a new Intro.js object. In this object, you define an array of objects that contains each step of the tour in sequence:

$scope.IntroOptions = {
  steps: [
    {
      element: '#toolbar-travellers-info-icon',
      intro: "<div class='tour-header'>Open Travellers Information Menu</div>" +
      "<div class='tour-step'>Click <b>" + TOUR.iconUsers + " Travellers Information</b> 
          icon to open the " +
      "travellers information menu.<br><br>" +
      "Use this menu to manage travellers, travellers groups " +
      "and also the language for each traveller.</div>",
      position:'left'
    },
    {
      element: '#travellersmenu',
      intro: "<div class='tour-header'>Travellers list</div>" +
      "<div class='tour-step'>Click <b>Travellers</b> 
          to view a list of travellers that belong to " +
      "the configured trips.</div>", 
      position: 'left'
    },
    {
      element: '#travellersmenu',
      intro: "<div class='tour-header'>Add new travellers</div>" +
      "<div class='tour-step'>You can also add a new traveller to the trips you have. Use the " +
      "<b>Filter by search</b> field to look for existing travellers. "+
      "Add them by clicking " + TOUR.iconAdd + " <b>Add travellers</b> at the " +
      "right corner of the menu.</div>",
      position: 'left'
    },
    {
      element: '#groupsmenu',
      intro: "<div class='tour-header'>Groups</div>" +
      "<div class='tour-step'>This tab allows travellers to create groups and 
          subgroups of travellers. " +
      "Any traveller that is already part of a group can add new travellers and subgroups.</div>",
      position: 'left'
    },
    {
      element: '#groupsmenu',
      intro: "<div class='tour-header'>Add new groups</div>" +
      "<div class='tour-step'>You can also add a new group of travellers to the 
          trips you have. Use the " +
      "<b>Filter by search</b> field to look for existing groups. "+
      "Add them by clicking " + TOUR.iconAdd + " <b>Add groups</b> 
          at the right corner of the menu.</div>",
      position: 'left'
    },
    {
      element: '#languagesmenu',
      intro: "<div class='tour-header'>Languages</div>" +
      "<div class='tour-step'>By default, users have <b>English</b> 
          language configured as the preferred language. "+
      "Travellers can add new languages to My Travel App at any time.</div>",
      position: 'left'
    },
    {
      element: '#tour-icon-dropdown',
      intro: "<div class='tour-header'>End of Travellers Info Tour</div>" + 
      "<div class='tour-step'>See this tour any time by clicking " + 
          TOUR.iconTour + " in the upper right toolbar </div>",
      position: 'left'
    }
  ],
  showStepNumbers: false,
  exitOnEsc:true,
  showBullets: false,
  scrollToElement:true,
  nextLabel: 'Next',
  prevLabel: 'Prev',
  skipLabel: 'End tour',
  doneLabel: 'Done'
};

For each step, you must define:

  • The target element, which is the ID of the HTML element that the step refers to
  • An element called intro, which consists of the HTML content for the tour step
  • A position element specifying the position of the step in the page

The next seven screenshots and accompanying code segments show how each of the steps defined in the Intro.js object for the Manager Travellers tour is displayed in the tour via the element, intro, and position sequence.

The tour's initial step uses the following portion of the Intro.js object code:

{element: '#toolbar-travellers-info-icon',
      intro: "<div class='tour-header'>Open Travellers Information Menu</div>" +
      "<div class='tour-step'>Click <b>" + TOUR.iconUsers + " Travellers Information</b> 
          icon to open the " +
      "travellers information menu.<br><br>" +
      "Use this menu to manage travellers, travellers groups " +
      "and also the language for each traveller.</div>",
      position:'left'
}
Screenshot of the tour's initial step
Screenshot of the tour's initial step

The tour step for listing travelers uses this portion of the Intro.js object code:

{
      element: '#travellersmenu',
      intro: "<div class='tour-header'>Add new travellers</div>" +
      "<div class='tour-step'>You can also add a new traveller to the trips you have. Use the " +
      "<b>Filter by search</b> field to look for existing travellers. "+
      "Add them by clicking " + TOUR.iconAdd + " <b>Add travellers</b> at the " +
      "right corner of the menu.</div>",
      position: 'left'
}
Screenshot of the tour's list-travelers step
Screenshot of the tour's list-travelers step

The tour step for adding new travelers uses this portion of the Intro.js object code:

{
      element: '#travellersmenu',
      intro: "<div class='tour-header'>Add new travellers</div>" +
      "<div class='tour-step'>You can also add a new traveller to the trips you have. Use the " +
      "<b>Filter by search</b> field to look for existing travellers. "+
      "Add them by clicking " + TOUR.iconAdd + " <b>Add travellers</b> at the " +
      "right corner of the menu.</div>",
      position: 'left'
}
Screenshot of the tour's step for adding new travelers
Screenshot of the tour's step for adding new travelers

The tour step that explains Groups tab uses this portion of the Intro.js object code:

{
      element: '#groupsmenu',
      intro: "<div class='tour-header'>Add new groups</div>" +
      "<div class='tour-step'>You can also add a new group of travellers to the 
          trips you have. Use the " +
      "<b>Filter by search</b> field to look for existing groups. "+
      "Add them by clicking " + TOUR.iconAdd + " <b>Add groups</b> 
          at the right corner of the menu.</div>",
      position: 'left'
}
Screenshot of the tour's Groups tab explanation step
Screenshot of the tour's Groups tab explanation step

The tour step for adding new groups uses this portion of the Intro.js object code:

{
      element: '#groupsmenu',
      intro: "<div class='tour-header'>Add new groups</div>" +
      "<div class='tour-step'>You can also add a new group of travellers to the 
          trips you have. Use the " +
      "<b>Filter by search</b> field to look for existing groups. "+
      "Add them by clicking " + TOUR.iconAdd + " <b>Add groups</b> 
          at the right corner of the menu.</div>",
      position: 'left'
}
Screenshot of the tour's step for adding new groups
Screenshot of the tour's step for adding new groups

The tour step that explains the Languages tab uses this portion of the Intro.js object code:

{
      element: '#languagesmenu',
      intro: "<div class='tour-header'>Languages</div>" +
      "<div class='tour-step'>By default, users have <b>English</b> 
          language configured as the preferred language. "+
      "Travellers can add new languages to My Travel App at any time.</div>",
      position: 'left'
}
Screenshot of the tour's step for explaining the Languages tab
Screenshot of the tour's step for explaining the Languages tab

The tour's final step uses this portion of the Intro.js object code:

{
      element: '#tour-icon-dropdown',
      intro: "<div class='tour-header'>End of Travellers Info Tour</div>" + 
      "<div class='tour-step'>See this tour any time by clicking " + 
          TOUR.iconTour + " in the upper right toolbar </div>",
      position: 'left'
}
Screenshot of the tour's final step
Screenshot of the tour's final step

Define other tour elements

In addition to the array of steps, you can define other elements — such as the labels of the buttons displayed on the tour and the use of an escape button to end the tour. Refer to the Intro.js library documentation for more information.

Set steps object to Intro.js variable

After defining all the steps for the Manage Travellers tour and the additional tour elements, we set the Intro.js object to the intro variable created before, using the setOptions() method for this purpose:

intro.setOptions($scope.IntroOptions);

Start Intro.js

In the HTML menu, specify both the controller and a function to be executed as the starting point for the tour. For the sample app, we specify the startTravellersTour() function:

$scope.startTravellersTour = function() {
     startTravellersPath();
     intro.start();
};

The startTravellersTour() function contains the call to start Intro.js, which is all that you need to start the tour. Note that this tutorial also executes another function before starting Intro.js. The startTravellersPath() function, which uses JQuery, ensures that the correct menu of the application opens when the tour starts:

var startTravellersPath = function() {
$timeout(function(){
    $("#toolbar-travellers-info-button").click();
    $timeout(function(){
        $("#loadTravellersMenu").click();
    },500);
    $('.dropdown').removeClass('open');
},500);
};

Ensure correct step transitions

Users must be able to navigate the tabs of the Travellers Information menu while the tour is taking place, so we also define an onchange event to ensure that the correct tab for each step is displayed while the tour is running:

intro.onchange (function(targetElement) {
    if (targetElement.id === 'travellersmenu') {
        $("#loadTravellersMenu").click();
    }
    if (targetElement.id === 'groupsmenu') {
        $("#loadGroupsMenu").click();
    }
    if (targetElement.id === 'languagesmenu') {
       $("#loadLanguagesMenu").click();
    }
});

End Intro.js

To finish execution of the tour, we define onexit and oncomplete events to ensure that the tour ends correctly:

intro.onexit (function(targetElement) {
    $("#toolbar-travellers-info-button").click();
});
intro.oncomplete (function(targetElement) {
    $("#toolbar-travellers-info-button").click();
});

Declare the controller file in your template

Finally, before using the new controller, you must declare it as a custom file in your EJS template file:

<script src="/static/js/guided_tour/travellersTourController.js"></script>

Conclusion

This tutorial introduced the Intro.js library's interactive, dynamic approach to user documentation and showed you all the steps necessary to create a guided tour using the library. It's easy to integrate Intro.js with any website — including, as we've shown, web apps running in the Bluemix cloud. Using Bluemix and Intro.js together can greatly enhance the user experience for your web applications.

Acknowledgment

We gratefully acknowledge Leonardo Faccio Demo for his help with deploying My Travel App to Bluemix.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Web development, Open source, Cloud computing
ArticleID=1017045
ArticleTitle=Add interactive documentation to your JavaScript apps with Intro.js
publish-date=10092015