Home

Awesome

Tourist.js Build Status

Tourist.js is a simple library for creating guided tours through your app. It's better suited to complex, single-page apps than websites. One of our main requirements was the ability to control the interface for each step. For example, a step in the tour might need to open a window or menu to work correctly. Tourist gives you hooks to do this.

Basically, you specify a series of steps which explain elements to point at and what to say. Tourist.js manages moving between those steps.

Install

The code is available via bower install tourist. Once you have the code, you just need to include the javascript file. An optional CSS file with minimal styling is included as well.

<script src="tourist.js"></script>

<!-- Optional! -->
<link rel="stylesheet" href="tourist.css" type="text/css" media="screen">

Dependencies

Tourist depends on Backbone and jQuery. jQuery UI is optional. Tourist uses an easing function from jQuery UI if present in the show effect with the Bootstrap tip implementation.

Tourist comes with the ability to use either Bootstrap 3 popovers (default) or QTip2 tips, so you'll need either Bootstrap 3 CSS (only the CSS is necessary!) or QTip2 installed. You can write your own tooltip connector if you'd like.

Basic Usage

Making a simple tour is easy:

var steps = [{
  // this is a step object
  content: '<p>Hey user, check this out!</p>',
  highlightTarget: true,
  nextButton: true,
  target: $('#thing1'),
  my: 'bottom center',
  at: 'top center'
}, {
  ...
}, ...]

var tour = new Tourist.Tour({
  steps: steps,
  tipOptions:{ showEffect: 'slidein' }
});
tour.start();

Reference

Tour object

Create one like this:

var steps = [{...}, {...}]
var tour = new Tourist.Tour({
  steps: steps
});
tour.start();

Options

Methods

The step object

The 'step object' is a simple javascript object that specifies how a step will behave.

A simple Example of a step object:

{
  content: '<p>Welcome to my step</p>',
  target: $('#something-to-point-at'),
  closeButton: true,
  highlightTarget: true,
  setup: (tour, options) {
    // do stuff in the interface/bind
  },
  teardown: function(tour, options) {
    // remove stuff/unbind
  }
}

Step object options

Step object function options

All functions on the step will have the signature function(tour, options){} where

setup()

setup() is called before a step is shown. Use it to scroll to your target, hide/show things, etc.

this is the step object itself.

setup() can return an object. Properties in the returned object will override properties in the step object.

Example, the target might be dynamic so you would specify:

{
  setup: function(tour, options) {
    options.model.bind('change:thing', this.onThingChange);
    return { target: $('#point-to-me') };
  }
}

teardown()

teardown() will be called right before hiding the step. Use to unbind from things you bound to in setup().

this is the step object itself.

{
  teardown: function(tour, options) {
    options.model.unbind('change:thing', this.onThingChange);
  }
}

Return nothing from teardown()

bind

bind is an array of function names to bind. Use this for event handlers you use in setup().

Will bind functions to the step object as this, and the first 2 args as tour and options. i.e.

{
  bind: ['onChangeSomething'],
  onChangeSomething: function(tour, options, model, value) {
    tour.next()
  },
  setup: function(tour, options) {
    options.document.bind('change:something', this.onChangeSomething);
    return {};
  },
  teardown: function(tour, options) {
    options.document.unbind('change:something', this.onChangeSomething)
  }
}

Tip objects

You won't be creating Tip objects yourself, the Tour object will handle that. But you can choose which tip implementation to use and you can pass the tip options to use on creation.

Bootstrap tips

Bootstrap tips are the default tip. They use only the markup and CSS from Bootstrap. Bootstrap's javascript for tooltips or popovers is not necessary. Here's how to use them.

var tour = new Tourist.Tour({
  steps: steps,
  tipClass: 'Bootstrap'
  tipOptions: {
    showEffect: 'slidein'
  }
});

It supports some options you can specify in tipOptions:

Only one effect is defined at this time: slidein. And you need to include jQuery UI to get the proper easing function for it.

Effects are specified as functions on Tourist.Tip.Bootstrap.effects take a look at the implementation for an existing effect to get an idea how to extend.

QTip2 tips

An alternative is to use QTip2 tips. You need to include both the QTip javascript and CSS for these to work.

var tour = new Tourist.Tour({
  steps: steps,
  tipClass: 'QTip'
  tipOptions: {
    ...
  }
});

Options accepted are any options QTip supports and in their format.

Your own Tip implementation

You can use your own tip implementation if you want. Make a class and hang it off the Tourist.Tip namespace. See the tips code for examples. The bootstrap example is probably most interesting. Here is a basic example in coffeescript:

# you need to provide these implementations at a minimum
class Tourist.Tip.MyTip extends Tourist.Tip.Base
  initialize: (options) ->
    # options would be: { likes: ['turtles'] }
    $('body').append(@el)

  show: ->
    @el.show()

  hide: ->
    @el.hide()

  _getTipElement: ->
    @el

  # Jam the content into our element
  _renderContent: (step, contentElement) ->
    @el.html(contentElement)

tour = new Tourist.Tour
  steps: steps
  tipClass: 'MyTip'
  tipOptions: { likes: ['turtles'] }

Testing/Building

Browser support

Officially tested on latest Firefox and Chrome

Structure

Contributing

Release History

MIT License