Quick and easy way to build your product tours with Twitter Bootstrap Popovers.
Note: This library does not depend on the full Bootstrap package. The only dependencies are the tooltip and popover files.
Restart tour<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>
var tour = new Tour();
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!
tour.start();
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();
Default options:
var tour = new Tour({ name: "tour", keyboard: true, useLocalStorage: false, afterGetState: function (key, value) {}, afterSetState: function (key, value) {}, afterRemoveState: function (key) {}, 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
, afterSetState
and afterRemoveStateYou may want to do something right after
Bootstrap Tour read or write the state. Just pass functions to
afterGetState
, afterSetState
or afterRemoveState.
Your functions can have two parameters:
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.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. If the function returns a Promise object (including jQuery.Deferred), the first step won't be shown until the Promise is resolved.
onEnd
Function to execute when the tour ends.
onShow
Function to execute right before each step is shown. If the function returns a Promise object (including jQuery.Deferred), the next step won't be shown until the Promise is resolved.
onHide
Function to execute right before each step is hidden. If the function returns a Promise object (including jQuery.Deferred), the current step won't be hidden until the Promise is resolved.
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 });
Bug reports and pull requests are much needed!
Code licensed under the Apache License v2.0. Documentation licensed under CC BY 3.0. Well, the same licenses as Bootstrap. We are lazy! ;)