Bootstrap Tour, easy product tours with Bootstrap from Twitter

Usage

1. Link to the JavaScript dependencies.

<script src="jquery.js"></script><script src="jquery.cookie.js"></script><script src="bootstrap.tooltip.js"></script><script src="bootstrap.popover.js"></script><script src="bootstrap-tour.js"></script>

2. Initialize the tour

var tour = new Tour();

3. Add steps

tour.addStep({
 element: "", /* html element next to which the step popover should be shown */
 title: "", /* title of the popover */
 content: "" /* content of the popover */
});

You can add as many steps as you want, but not too much or your users will fell asleep!

4. Start the tour

tour.start();

Options

Useful Methods

Bootstrap Tour saves the current step and will not display the tour again to users who have already completed it.

If, for some reasons, you want to force the tour to be displayed, pass true to the start() method.

tour.start(true);

Sometimes you want to end the tour prematurely:

tour.end();

Or skip to the next step:

tour.next();

Or go back to the previous step:

tour.prev();

Or skip to a specific step:

tour.showStep(i); // i is the position of the step in the tour, starting from 0 for the first step

Or restart the tour after it ended:

tour.restart();

Or verify if the tour ended:

tour.ended();

Initialization Options

Default options:

var tour = new Tour({
 name: "tour",
 keyboard: true,
 useLocalStorage: false,
 afterGetState: function (key, value) {},
 afterSetState: function (key, value) {},
 onStart: function (tour) {},
 onEnd: function (tour) {},
 onShow: function (tour) {},
 onHide: function (tour) {}
});

name

This option is used to build the name of the cookie or localStorage item where the tour state is stored. You can initialize several tours with different names in the same page and application.

keyboard

This option set the left/right arrow navigation. The default is true.

useLocalStorage

You can choose to save the tour state with localStorage instead of cookie. If you decide, you can safely remove the jquery.cookie plugin from the dependencies

afterGetState and afterSetState

You may want to do something right after Bootstrap Tour read or write the state. Just pass functions toafterGetState or afterSetState.

Your functions can have two parameters:

key Contains the name of the state being saved. It can be current_step (for the state where the latest step the visitor viewed is saved) or end (for the state which is saved when the user complete the tour). Note that Bootstrap Tour prepends the key with tour_ when saving the state. value The value of the state been saved. Can be the index of the current step if the key is current_step, or yes if the key is end.

A simple example if to send a post request to your server each time there is a change:

var tour = new Tour({
 afterSetState: function (key, value) {
 jQuery.post("/some/path", value);
 }
});

onStart

Function to execute when the tour starts.

onEnd

Function to execute when the tour ends.

onShow

Function to execute right before each step is shown.

onHide

Function to execute right before each step is hidden.

Step Options

Default options:

tour.addStep({
 path: "", // string
 element: "", // (required) jQuery selector
 placement: "right", // string|function
 title: "", // string|function
 content: "", // string|function
 next: 0, // number
 prev: 0, // number
 animation: true, // boolean
 onShow: function (tour) {}, // function
 onHide: function (tour) {} // function
});

path Path to the page on which the step should be shown. this allows you to build tours that span several pages! element HTML element on which the step popover should be shown. placement How to position the popover - top | bottom | left | right. title Step title content Step content next Index of the step to show after this one, starting from 0 for the first step of the tour. -1 to not show the link to next step. By default, the next step (in the order you added them) will be shown. This option should be used in conjunction with "prev". prev Index of the step to show before this one, starting from 0 for the first step of the tour. -1 to not show the link to previous step. By default, the previous step (in the order you added them) will be shown. This option should be used in conjunction with "next". animation Apply a css fade transition to the tooltip. onShow Function to execute right before the step is shown. It overrides the global onShow option. onHide Function to execute right before the step is hidden. It overrides the global onHide option. options (Object) Extend the options for one step. reflex (Bool) Enable the reflex mode : you can click on the element for continue the tour.

Contributing

Bug reports and pull requests are much needed!

License

Code licensed under the Apache License v2.0. Documentation licensed under CC BY 3.0. Well, the same licenses as Bootstrap. We are lazy! ;)