jQuery Tour - the flexible Tour Plugin

This jQuery based Tour plugin offers an easy way to guid your visitors and customers through your website or application and contains a lot of options and a powerfull API to fit your needs.

This plugin comes with four premade styles and it's easy to adopt it.

Check out the examples to see it in action

1. Include the jTour plugin in your document:

   <script src="js/jquery-1.7.1.min.js"></script>
   <script src="js/jTour.js"></script>

2. Include the css of your style in the header:

   <link rel="stylesheet" src="css/theme1/style.css">

3. create a new jTour Object after the you've included the script

   var myTour = jTour(tourdata[, options]);
   

4. start the tour with the start method:

   myTour.start();
   

You can autostart the tour with the autostart: true option

Please read more about the structure of the to urdata in the example section

Check out all available options

This plugin uses following Javascript librarys:

• jQuery v 1.7.1 required
• jQuery Easing v1.3 optional

If you would like to use a CDN you can use the following:

From Google CDN:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>

From jQuery CDN:

<script src="//code.jquery.com/jquery-1.7.1.min.js"></script>

From Microsoft CDN:

<script src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.1.min.js"></script>

Everytime you add a new jTour instance following HTML is added right before the closing tag of the body:

<div class="jTour_box [has-controls] [step-X]">
    <div class="jTour_arrow [n|e|s|w|nw|ne|se|sw|c]"></div>
    <div class="jTour_content"></div>
    <div class="jTour_progress">
        <div class="jTour_progress_bar"></div>
    </div>
    <ul class="jTour_nav">
        <li><a data-role="prev" title="previous" class="jTour_nav_btn prev">&nbsp;</a></li>
        <li><a data-role="play" title="play" class="jTour_nav_btn play">&nbsp;</a></li>
        <li><a data-role="pause" title="pause" class="jTour_nav_btn pause" style="display: none;">&nbsp;</a></li>
        <li><a data-role="stop" title="stop" class="jTour_nav_btn stop">&nbsp;</a></li>
        <li><a data-role="next" title="next" class="jTour_nav_btn next">&nbsp;</a></li>
        <li><a data-role="slower" title="slower" class="jTour_nav_btn slower">&nbsp;</a></li>
        <li><a data-role="faster" title="faster" class="jTour_nav_btn faster">&nbsp;</a></li>
    </ul>
</div>

has-control will get added if showControls is true

step-X will get added on every new step (where X is the current step starting with 0)

The div.jTour_arrow get the position of each step

The ul.jTour_nav is missing if showControls is false

The Overlay

<div class="jTour_overlay" style="opacity: XX; height: XXpx;">
</div>

The Overlay is styled in the style.css of the selected theme.

opacity is the value of overlayOpacity

height is the actual document height

not all CSS properties are working properly with the exposure object

If you save the Tour in a variable you have a powerful API to work with.

var myTour = jTour(tourdata);

The myTour Object offers now several methods:

myTour.start([step]); //starts the tour at step [step] (default = 0)

myTour.stop(); //stops the tour

myTour.pause([toggle]); //pauses the tour or toggles it if toggle = true (default = false)

myTour.play(); //continues a paused tour

myTour.restart([step]); //same as myTour.start(0);

myTour.next(); //goes to the next step

myTour.prev(); //goes to the previous step

myTour.faster([value]); //increase the speed of the tour with [value] (default 0.25)

myTour.slower([value]); //decrease the speed of the tour with [value] (default 0.25)

myTour.moveTo(x, y, animate); //moves the box to an absolute position. animate is the duration of the animation (default = 0)

myTour.offset(x, y, animate); //moves the box to its relative position. animate is the duration of the animation (default = 0)

myTour.scroll(x, y, animate); //scrolls the window to the desired position. animate is the duration of the animation (default = 0)

Furthermore these variables are available:

myTour.tourdata; //contains the tourdata array

myTour.content; //the jQuery DOM element of the content

myTour.box; //the jQuery DOM element of the whole box

myTour.overlay; //the jQuery DOM element of the overlay

To create a working jTour you have setup an array which contains the tourdata

Example 1

create an empty array

var tourdata = [];  

Now create a single step

var mystep = {
    html: "Hello World"
};

Let's add this step to the tourdata

tourdata.push(mystep);

This creates a tourdata array with one step in it.

Now we have our first tour and can simple start it with these lines:

var myTour = jTour(tourdata);
myTour.start();

Check out example 1 to see the Demo to this example.

Example 2

var tourdata = [
   {
      html: "Hello World"
   },{
      html: "Welcome to the Tour",
      live: 5000,
      delayIn: 500
   }
];
var myTour = jTour(tourdata);
myTour.start(); 

This starts a tour with two steps. The first is equal to example one the second step displays the message five seconds (5000 milliseconds) and the time to reveal the message (box) does take half a second (or 500 milliseconds)

If you didn't set the live property the duration depends on the content

Check out the demo for example 2

Example 3

var tourdata = [
   {
      html: "Hello World"
   },{
      html: "Welcome to the Tour",
      live: 5000,
      delayIn: 500
   },{
      html: "Lorem Ipsum Bla Bla",
      element: 'h2', //use the first h2 tag as target element
      position: 's'
   },{
      html: "Second List Entry",
      element: $('li').eq(1), //use the second (starting with 0) a tag within a li tag as target element
      position: 'e' //display the box right to the target element (east) 
  }
];
var myTour = jTour(tourdata);
myTour.start(); 

In this example we added two additional steps. They have an element and a position property.

Ceck out the demo for example 3

Example 4

This example show how to use an imagemap with the tour plugin

The Markup

<img src="img/image.jpg" width="875" height="656" usemap="#image" alt="">
<map name="image">
    <area shape="rect" coords="81,264,111,295" href="#" alt="Bernice Hibbert" >
    <area shape="rect" coords="471,142,502,173" href="#" alt="Mrs. Glick" >
    <area shape="rect" coords="103,442,133,473" href="#" alt="Nahasapeemapetilon Manjula" >
    <area shape="rect" coords="234,238,264,268" href="#" alt="John Popovich" >
    <area shape="rect" coords="646,200,676,230" href="#" alt="Legs" >
    <area shape="rect" coords="18,504,48,535" href="#" alt="Rainier Luftwaffe Wolfcastle" >
    <area shape="rect" coords="241,159,271,190" href="#" alt="Kearney Zzyzwicz" >
    <area shape="rect" coords="455,358,485,388" href="#" alt="Blue-Haired Lawyer" >
</map>

Use only rectangular shapes shape="rect"

var tourdata = [
   {
      element: $('area').eq(0),
      html: "Bernice Hibbert",
      position: 'n'
   },{
      element: $('area').eq(1),
      html: "Mrs. Glick",
      position: 'n'
   },{
   ...

Check out example 4 to see the Demo to this example.

All possible options of a single step

The only required property is "html" which is the content of the step. Furthermore you can set a lot more option for each step explicitly:

{
    html: 'Hello World', //The content of the box (required)
    position: 'c' //position of the box
    live: 'auto', //duration of the box ('auto' is for calculating)
    offset: 0, //offset in pixels
    wait: 0, //pause time before the next box is displayed
    expose: false, //exposures the target element
    overlayOpacity: 0.2, //defines the opacity of the overlay (false disables it)
    delayIn: 200,  //time to reveal the box
    delayOut: 100, //time to hide the box
    animationIn: 'fadeIn',  //animation type for showing the box
    animationOut: 'fadeOut', //animation type for hiding the box
    onBeforeShow: function(element) {}, //callback
    onShow: function(element) {}, //callback
    onBeforeHide: function(element) {}, //callback
    onHide: function(element) {}, //callback
    onStep: function(element, percentage) {}, //callback
    element: 'body', //the target element for the box
    goTo: null //required for multipage tours
}

Check out example 5 and example 6!

Please check out the Options Section too!

How to track steps with Google Analytics?

You can track the steps by using the jTour callbacks:

var myTour = jTour(tourdata,{
   onChange:function(current){
	_gaq.push(['_trackEvent', 'tour', 'reached step '+(current+1)]);
   },
   onFinish:function(current){
	_gaq.push(['_trackEvent', 'tour', 'finished')]);
   }
});

Read more about Google Analytics API here

How to avoid flickering during scrolling on iPad/iPhone?

iOS has a strange behavior if you animate both axis ('xy'). If you doesn't need them both set the axis property to 'y' (or 'x')

How to start the tour only once?

Sometimes you would like to autostart the tour only on the first visit of a customer. You can set a cookie to check if the visitor was here already. Include the setCookie and getCookie function in your script and use this snippet:

var myTour = jTour(tourdata,{
   autostart: !getCookie('tourwasplayed'),
   onStop: function(){
      //set the cookie with value 1 (true) and expire date in 365 days
      setCookie('tourwasplayed', 1, 365);
   }
});

You can also set the cookie only when the tour has been finished (onFinish)

How to change the style on-the-fly?

You can change the style by just change the stylesheet. First you have to give the link tag in the header an id:

<link href="css/theme1/style.css" id="mystyle" rel="stylesheet">

Now you can change the style for instance at the beginning of the tour:

var myTour = jTour(tourdata,{
   onStart: function(){
      var version = 2; //set a version from 1 to 8
      document.getElementById('mystyle').href = 'css/theme'+version+'/style.css';
   }
});

Version 1.2 (12/27/2011)

new callbacks: onPause onPlay
new API Methods: pause() play()
4 new styles
improved CSS (updated your stylesheet!)
performance improvements
bug bugfixes

Version 1.1 (12/20/2011)

added exposure feature
small bugfixes

Version 1.0 (12/13/2011)

initial release

I've used the following images, icons or other files as listed.

• jQuery Easing Plugin by George McGinley Smith

Files are maybe not included because of the license

Once again, thank you so much for purchasing this plugin. As I said at the beginning, I'd be glad to help you if you have any questions relating to this plugin. No guarantees, but I'll do my best to assist. If you have a more general question relating to plugins on CodeCanyon, you might consider visiting the forums and asking your question in the "Item Discussion" section.

Xaver Birsak – revaxarts.com