// Instance the tour
var tour = new Tour();
// Add your steps. Not too many, you don't really want to get your users sleepy
tour.addSteps([
{
element: "#my-element", // string (jQuery selector) - html element next to which the step popover should be shown
title: "Title of my step", // string - title of the popover
content: "Content of my step" // string - content of the popover
},
{
element: "#my-other-element",
title: "Title of my step",
content: "Content of my step"
}
]);
// Initialize the tour
tour.init();
// Start the tour
tour.start();
This option is used to build the name of the
storage item where the tour state is stored. You can
initialize several tours with different names in the same page and
application.
'tour'
container
String
Appends the step popover to a specific element. See Usage section of
Popover.
'body'
keyboard
Boolean
This option set the left and right arrow navigation.
true
storage
Object
The storage system you want to use. could be the objects window.localStorage,
window.sessionStorage or your own object.
You can set this option as
false to disable storage
persistence (the tour starts from beginning everytime the page is
loaded). Read more about DOM Storage interfaces.
window.localStorage
debug
Boolean
Set this option to true to have some useful informations printed in the
console.
false
backdrop
Boolean
Show a dark backdrop behind the popover and its element,
highlighting the current step.
false
redirect
Boolean|Function
Set a custom function to execute as redirect function.
The default redirect relies on the traditional
document.location.href
true
orphan
Boolean
Allow to show the step regardless whether its element is not set, is
not present in the page or is hidden. The step is fixed
positioned in the middle of the page.
false
duration NEW
Boolean|String
Set a expiration time for the steps. When the current step expires,
the next step is automatically shown. See it as a sort of guided, automatized tour
functionality. The value is specified in milliseconds
false
basePath
String
Specify a default base path prepended to the
path option of every single
step. Very useful if you need to reuse the same tour on different
environments or sub-projects.
''
template
String|Function
String or function that returns a string of the HTML template for
the popovers. If you pass a Function, two parameters are available:
i is the position of step in the tour and
step is the an object that contains all the other step
options.
From version 0.5, the navigation template is included inside the
template so you can easily rewrite it. However, Bootstrap Tour maps the
previous, next and end logics to the elements
which have the related data-role
attribute. Therefore, you can also have multiple elements with the same
data-role attribute.
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:
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) {
$.post("/some/path", value);
}
});
function(key, value) { }
onStart
Function
Function to execute when the tour starts.
function(tour) { }
onEnd
Function
Function to execute when the tour ends.
function(tour) { }
onShow
Function
Function to execute right before each step is shown.
function(tour) { }
onShown
Function
Function to execute right after each step is shown.
function(tour) { }
onHide
Function
Function to execute right before each step is hidden.
function(tour) { }
onHidden
Function
Function to execute right after each step is hidden.
function(tour) { }
onNext
Function
Function to execute when next step is called.
function(tour) { }
onPrev
Function
Function to execute when prev step is called.
function(tour) { }
onPause NEW
Function
Function to execute when pause is called. The second argument refers to the
remaining duration.
function(tour, duration) { }
onResume NEW
Function
Function to execute when resume is called. The second argument refers to the
remaining duration.
Path to the page on which the step should be shown. This
allows you to build tours that span several pages!
''
element
String (jQuery selector)
HTML element on which the step popover should be shown. If orphan is false, this option is required.
''
placement
String|Function
How to position the popover. Possible choices:
'top',
'bottom',
'left',
'right'.
'right'
title
String|Function
Step title
''
content
String|Function
Step content
''
next
Integer
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.
0
prev
Integer
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.
0
animation
Boolean
Apply a css fade transition to the tooltip.
true
container
String (jQuery selector)
Attachment of popover. Pass an element to append the popover
to. By default the popover is appended after the 'element' above.
This option is particularly helpful for Internet Explorer.
'body'
backdrop
Boolean
Show a dark backdrop behind the popover and its element,
highlighting the current step.
false
redirect
Boolean|Function
Set a custom function to execute as redirect function.
The default redirect relies on the traditional
document.location.href
true
reflex
Boolean
Enable the reflex mode: you can click on the element for
continue the tour.
false
orphan
Boolean
Allow to show the step regardless whether its element is not set, is
not present in the page or is hidden. The step is fixed
positioned in the middle of the page.
false
duration NEW
Boolean|String
Set a expiration time for the stes. When the step expires,
the next step is automatically shown. See it as a sort of guided, automatized tour
functionality. The value is specified in milliseconds
false
template
String|Function
String or function that returns a string of the HTML template for
the popovers. If you pass a Function, two parameters are available:
i is the position of step in the tour and
step is the an object that contains all the other step
options.
From version 0.5, the navigation template is included inside the
template so you can easily rewrite it. However, Bootstrap Tour maps the
previous, next and end logics to the elements
which have the related data-role
attribute. Therefore, you can also have multiple elements with the same
data-role attribute.
Function to execute right before the step is shown. It overrides the
global onShow option.
function(tour) { }
onShown
Function
Function to execute right after the step is shown. It overrides the
global onShown option.
function(tour) { }
onHide
Function
Function to execute right before the step is hidden. It overrides
the global onHide option.
function(tour) { }
onHidden
Function
Function to execute right after the step is hidden. It overrides the
global onHidden option.
function(tour) { }
onNext
Function
Function to execute when next step is called. It overrides the
global onNext option.
function(tour) { }
onPrev
Function
Function to execute when prev step is called. It overrides the global
onPrev option.
function(tour) { }
onPause NEW
Function
Function to execute when pause is called. The second argument refers to the
remaining duration. It overrides the global the
onPause option
function(tour, duration) { }
onResume NEW
Function
Function to execute when resume is called. The second argument refers to the
remaining duration. It overrides the global
onResume option
function(tour, duration) { }
Methods Always in control
Name
Description
init()
Initialize the tour. You must do it before calling start.
start(true)
Start the tour. Pass true to force the start.
restart()
Restart the tour after it ended.
end()
End the tour prematurely.
next()
Skip to the next step.
prev()
Go back to the previous step.
goTo(i)
UPDATED
Skip to a specific step. Pass i as the
position of the step in the tour, starting from 0 for the first step. From version 0.7.0, the method has been renamed since some Javascript compilers
are confused by the property name goto, which is a reserved word)
pause()
Pause the duration timer. It works only if tour or current stap has duration.
resume()
Resume the duration timer. It works only if tour or current stap has duration.
ended()
Verify if the tour ended. Returns boolean.
Contributing Do you think we need help? You are totally right
// Start a server and run the demo page
grunt
grunt run
// Compile all sources
grunt build
// Compile all sources and run the tests
grunt test
// Automatically release a new version (see below for more details)
grunt release
Running grunt run will start a small server on port 3000 and opens the browser to the webpage. It will also start watching for changes in the index.coffee which will trigger then live reloading of the page in the browser.
Tests are written using Jasmine and they run headlessly through PhantomJS.
Simply run grunt test or watch them with grunt watch:test (this will execute them automatically every time you change the specs).
You can also open the _SpecRunner.html (generated after you run grunt test) to run the tests in the browser.
Team
Ulrich Sossou
Emanuele Marchi
Luca Molinari
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! ;)