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.
► Start 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, debug: false, afterGetState: function (key, value) {}, afterSetState: function (key, value) {}, afterRemoveState: function (key, value) {}, onStart: function (tour) {}, onEnd: function (tour) {}, onShow: function (tour) {}, onHide: function (tour) {}, onShown: 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
debug
Set this option to true to have some useful informations printed in the console.
afterGetState
, afterSetState
,
afterRemoveState
You may want to do something right after Bootstrap Tour read, write or remove
the state. Just pass functions to these.
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.
onEnd
Function to execute when the tour ends.
onShow
Function to execute right before each step is shown.
onShown
Function to execute right after each step is shown.
onHide
Function to execute right before each step is hidden.
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! ;)