---
title:                                  Roundtrip
tagline:                                bootstrap tour api
description:                            J1 Template Roundtrip - Present Bootstrap

tags:                                   [ Page, Roundtrip ]
index:                                  [ Template, Roundtrip, Images ]
categories:                             [ pages ]

toc:                                    true
scrollbar:                              false

permalink:                              /pages/public/learn/roundtrip/bs_tour_api/
regenerate:                             false

resources:                              [ bs_tour ]
resource_options:
  - attic:
      padding_top:                      400
      padding_bottom:                   50
      opacity:                          0.5
      slides:
        - url:                          /assets/images/pages/roundtrip/images/bootstrap-1920x1000-bw.jpg
          alt:                          Photo by Ricardo Gomez Angel on Unsplash
          badge:
            type:                       unsplash
            author:                     Ricardo Gomez Angel
            href:                       https://unsplash.com/@ripato/portfolio
---

// Enable the Liquid Preprocessor
// -----------------------------------------------------------------------------
:page-liquid:

// Set other global page attributes here
// -----------------------------------------------------------------------------
//:my-asciidoc-attribute:

//  Load Liquid procedures
// -----------------------------------------------------------------------------
{% capture set_env_entry_document %}themes/{{site.template.name}}/procedures/global/set_env_entry_document.proc{%endcapture%}

// Initialize entry document environmental attributes
// -----------------------------------------------------------------------------
{% include {{set_env_entry_document}} %}

// Load tag, url and data attributes
// -----------------------------------------------------------------------------
include::{includedir}/attributes.asciidoc[tag=tags]
include::{includedir}/attributes.asciidoc[tag=urls]
include::{includedir}/attributes.asciidoc[tag=data]

// Set local page attributes
// -----------------------------------------------------------------------------
:images-dir:                            {imagesdir}/pages/roundtrip/100_present_images


// Page content
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// Include sub-documents
// -----------------------------------------------------------------------------

== Bootstrap Tour

lorem:sentences[5] +
lorem:sentences[3] +

=== Global Options

lorem:sentences[5] +
lorem:sentences[3] +

[source, js]
----
var tour = Tour({
  name: "tour",
  steps: [],
  container: "body",
  keyboard: true,
  storage: window.localStorage,
  debug: false,
  backdrop: false,
  backdropContainer: 'body',
  backdropPadding: 0,
  redirect: true,
  orphan: false,
  duration: false,
  delay: false,
  basePath: "",
  template: '<div class="popover tour">
    <div class="arrow"></div>
    <h3 class="popover-title"></h3>
    <div class="popover-content"></div>
    <div class="popover-navigation">
        <button class="btn btn-default" data-role="prev"> Prev</button>
        <span data-role="separator">|</span>
        <button class="btn btn-default" data-role="next">Next »</button>
    </div>
    <button class="btn btn-default" data-role="end">End tour</button>
  </div>',
  afterGetState: function (key, value) {},
  afterSetState: function (key, value) {},
  afterRemoveState: function (key, value) {},
  onStart: name(tour) {},
  onEnd: name(tour) {},
  onShow: name(tour) {},
  onShown: name(tour) {},
  onHide: name(tour) {},
  onHidden: name(tour) {},
  onNext: name(tour) {},
  onPrev: name(tour) {},
  onPause: name(tour, duration) {},
  onResume: name(tour, duration) {},
  onRedirectError: name(tour) {}
});
----

[cols="1,1,3a,7a", options="header", width="100%", role="table-responsive-stacked-lg"]
|===============================================================================
|Name |Type |Default |Description

|name
|String
|`tour`
|This option is used to build the name of the storage item
where the tour state is stored. The name should contain only
alphanumerics, underscores and hyphens. You can initialize several tours
with different names in the same page and application.

|steps
|Array
|`[]`
|A list of object representing the steps to be included in
the tour. Jump to link:#step-options[Step options] for the single step
API.

|container
|String
|`body`
|Appends the step popover to a specific element. +
_See Usage section of
http://getbootstrap.com/javascript/#popovers[Popover]._

|autoscroll
|Boolean
|`true`
|Autoscrolls the window when the step popover is out of view.

|keyboard
|Boolean
|`true`
|This option set the left and right arrow navigation.

|storage
|Object
|`window.localStorage`
|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 every time the page is loaded). +
_Read more about
https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage[DOM
Storage interfaces]._

|debug
|Boolean
|`false`
|Set this option to true to have some useful
informations printed in the console.

|backdrop
|Boolean
|`false`
|Show a dark backdrop behind the popover and its
element, highlighting the current step.

|backdropContainer
|String
|`body`
|HTML element (jQuery selector) on which the backdrop should be shown.

|backdropPadding
|Number\|Object
|`0`
|Add padding to the backdrop element
that highlights the step element. +
It can be a number or a object containing optional `top`, `right`,
`bottom` and `left` numbers.

|redirect
|Boolean \|Function
|`true`
|Set a custom function to execute as
redirect function. The default redirect relies on the traditional
`document.location.href`.

|orphan
|Boolean\|String\|function
|`false`
|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.

|duration
|Boolean\|Number
|`false`
|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.

|delay
|Boolean\|Number
|`0`
|Specifies a delay for the showing and hiding the tour steps. It can be:
* a falsy - there is no delay
* a number - used as a delay for both showing and hiding. In milliseconds
* a object containing optional `show` and `hide` numbers - defines the
  delays for showing and hiding respectively.

|basePath
|String
|empty 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 callout:1[]
|String\|Function
|See *Description*
|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. +

|afterGetState \| afterSetState \| afterRemoveState  callout:2[]
|Function
|`name(key, value){}`
|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.

|onStart
|Function
|`name(tour){}`
|Function to execute when the tour starts.

|onEnd
|Function
|`name(tour){}`
|Function to execute when the tour ends.

|onShow
|Function
|`name(tour){}`
|Function to execute right before each step is shown.

|onShown
|Function
|`name(tour){}`
|Function to execute right after each step is shown.

|onHide
|Function
|`name(tour){}`
|Function to execute right before each step is hidden.

|onHidden
|Function
|`name(tour){}`
|Function to execute right after each step is hidden.

|onNext
|Function
|`name(tour){}`
|Function to execute when next step is called.

|onPrev
|Function
|`name(tour){}`
|Function to execute when prev step is called.

|onPause
|Function
|`name(tour, duration){}`
|Function to execute when pause is called. The
second argument refers to the remaining duration.

|onResume
|Function
|`name(tour, duration){}`
|Function to execute when resume is called. The
second argument refers to the remaining duration.

|onRedirectError
|Function
|`name(tour){}`
|Function to execute when there is a
redirection error. This happens when bootstrap tour cannot redirect to
the path of the step.

|===============================================================================

.Template default settings callout:1[]
[source, html]
----
<div class="popover tour">
  <div class="arrow"></div>
  <h3 class="popover-title"></h3>
  <div class="popover-content"></div>
  <div class="popover-navigation">
    <button class="btn btn-default" data-role="prev'"> Prev</button>
    <span data-role="separator">\|</span>
    <button class="btn btn-default" data-role="next">Next »</button>
    <button class="btn btn-default" data-role="end">End tour</button>
  </div>
</div>
----

State function example callout:2[]
[source, js]
----
var tour = Tour({
  afterSetState: function (key, value) {
    $.post("/some/path", value);
  }
});
----


=== Step Options

[source, js]
----
tour.addStep({
  path: "",
  host: "",
  element: "",
  placement: "right",
  title: "",
  content: "",
  next: 0,
  prev: 0,
  animation: true,
  container: "body",
  backdrop: false,
  backdropContainer: 'body',
  backdropPadding: false,
  redirect: true,
  reflex: false,
  orphan: false,
  template: "",
  onShow: name(tour) {},
  onShown: name(tour) {},
  onHide: name(tour) {},
  onHidden: name(tour) {},
  onNext: name(tour) {},
  onPrev: name(tour) {},
  onPause: name(tour) {},
  onResume: name(tour) {},
  onRedirectError: name(tour) {}
});
----

// |Name |Type |Description |Default

[cols="1,1,3a,7a", options="header", width="100%", role="table-responsive-stacked-lg"]
|===============================================================================
|Name |Type |Default |Description

|path
|String or RegExp
|`''`
|Path to the page on which the step should be
shown. This allows you to build tours that span several pages.

|host NEW
|String or RegExp
|`''`
|Host of the page on which the step should
be shown. This allows you to build tours for several sub-domains.

|element
|String
|`''`
|HTML element (jQuery selector) on which the step
popover should be shown. +
_If orphan is false, this option is required._

|placement
|String\|Function
|`right`
|How to position the popover. Possible
choices: `'top'`, `'bottom'`, `'left'`, `'right'`, `'auto'`. When "auto"
is specified, it will dynamically reorient the popover. For example, if
placement is "auto left", the popover will display to the left when
possible, otherwise it will display right.

|title
|String\|Function
|`''`
|Step title

|content
|String\|Function
|`''`
|Step content

|next
|Integer
|`0`
|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
|Integer
|`0`
|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
|Boolean
|`true`
|Apply a css fade transition to the tooltip.

|container
|String
|`body`
|Attachment of popover. Pass an element (jQuery selector) to append the
popover to. By default the popover is appended
after the 'element' above. This option is particularly helpful for
Internet Explorer.

|backdrop
|Boolean
|`false`
|Show a dark backdrop behind the popover and its
element, highlighting the current step.

|backdropContainer NEW
|String (jQuery selector)
|`body`
|HTML element on which the backdrop should be shown.

|backdropPadding NEW
|Boolean\|Object
|`0`
|Add padding to the backdropelement that highlights the step element. +
It can be a number or a object containing optional `top`, `right`,
`bottom` and `left` numbers.

|redirect
|Boolean\|Function
|`true`
|Set a custom function to execute as redirect function. The default
redirect relies on the traditional `document.location.href`.

|reflex UPDATED
|Boolean\|String
|`false`
|Enable the reflex mode: attach an
handler on `click` on the step element to continue the tour. +
In order to bind the handler to a custom event, you can pass a string
with its name. +
Also, the class `tour-step-element-reflex` is added to the element, as
hook for your custom style (e.g: cursor: pointer).

|orphan
|Boolean\|String\|Function
|`false`
|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. +
You can use a string or function that returns a string of the HTML
template for the orphan popovers.

|duration NEW
|Boolean\|String
|`false`
|Set a expiration time for the steps. 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.

|template
|String\|Function
|See *blabla*
|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 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.

|onShow
|Function
|`name(tour) {}`
|Function to execute right before the step is shown.
It overrides the global `onShow` option.

|onShown
|Function
|`name(tour) {}`
|Function to execute right after the step is shown.
It overrides the global `onShown` option.

|onHide
|Function
|`name(tour) {}`
|Function to execute right before the step is hidden.
It overrides the global `onHide` option.

|onHidden
|Function
|`name(tour) {}`
|Function to execute right after the step is hidden.
It overrides the global `onHidden` option.

|onNext
|Function
|`name(tour) {}`
|Function to execute when next step is called. It
overrides the global `onNext` option.

|onPrev
|Function
|`name(tour) {}`
|Function to execute when prev step is called. It
overrides the global `onPrev` option.

|onPause NEW
|Function
|`name(tour, duration) {}`
|Function to execute when pause is called. The
second argument refers to the remaining duration. It overrides the
global the `onPause` option.

|onResume NEW
|Function
|`name(tour, duration) {}`
|Function to execute when resume is called. The
second argument refers to the remaining duration. It overrides the
global `onResume` option.

|onRedirectError NEW
|Function
|`name(tour) {}`
|Function to execute when there is a
redirection error. This happens when bootstrap tour cannot redirect to
the path of the step. It overrides the global `onRedirectError` option.

|===============================================================================


=== Methods

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

[cols="3,9a",options="header",]
|===============================================================================
|Name |Description
|addSteps(`[]`)
|Add multiple steps to the tour. Pass an array of objects.

|addStep(`{}`)
|Add single step to the tour. Pass an object.

|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`)
|Skip to a specific step. Pass `i` as the index of
the step in the tour (0-based). +
_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 step has duration.

|resume()
|Resume the duration timer. It works only if tour or current step has duration.

|ended() |Verify if the tour ended. Returns boolean.

|getStep(`i`)
|Get the step object. Pass `i` as the index of the step in the tour (0-based).

|getCurrentStep()
|Get the index of the current step.

|setCurrentStep(`i`)
|Override the current step. Pass `i` as the index of the step in the
tour (0-based).

|redraw()
|Triggers a redraw on the overlay element. Useful for dynamically sized
tour targets.

|===============================================================================