1. Start
  2. General
  3. How to Start
  4. Requirements
  5. The Markup
  6. Options
  7. The API
  8. Examples
  9. F.A.Q.
  10. Changelog
  11. Sources and Credits

jQuery Tour

the flexible Tour Plugin


Thank you for purchasing my plugin. If you have any questions that are beyond the scope of this help file, please feel free to start a discussion at my support forum. Thanks so much!

General


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

How to Start


  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

Requirements


This plugin uses following Javascript librarys:

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>

 

The Markup


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

Options


option default possible values description since
speed 1 > 0.1 the multiplikator for the general duration of the steps 1.0
axis xy 'x', 'y', 'xy' The animated axis (iOS can't animate on both axis without flickering) 1.0
autostart false true | false starts the Tour immediately after initialization 1.0
autoplay true true | false steps change without user action 1.0
pauseOnHover true true | false pauses the autoplay on mouseover 1.0
keyboardNav true true | false activated keyboard navigation (left, right, up, down arrow, ESC, space) 1.0
showProgress true true | false shows the progressbar 1.0
showControls true true | false enables controls under the content. 1.0
scrollBack false true | false scrolls back to the starting position after the tour has been finished 1.0
scrollDuration 300 integer time (in ms) how long scrolling to the next step take. unused if no scrolling is required 1.0
easing "swing" "linear" | "swing" the easing method for scrolling. Can be extended with the jquery.easing plugin 1.0
onStart function (current) {} callback function callback for start method. current is the id of the current step 1.0
onStop function (current) {} callback function callback for stop method. current is the id of the current step 1.0
onPause function (current) {} callback function callback for pause method. current is the id of the current step 1.2
onPlay function (current) {} callback function callback for continue method. current is the id of the current step 1.2
onChange function (current) {} callback function callback for every step. current is the id of the current step 1.0
onFinish function (current) {} callback function callback if the tour is finished. current is the id of the current step 1.0
Following options can get overwritten in each single step with the tou rdata:
position 'c' 'n' | 'e' | 's' | 'w' | 'ne' | 'se' | 'sw' | 'nw' | 'c' the position of the box 1.0
live 'auto' 'auto' | integer the duration of visibility of the box. If set to 'auto' the duration depends on the content 1.0
offset 0 integer | {x:integer, y:integer} the distance from the box to the target object. depending on the gravity the offset can set to the x or to the y axis 1.0
wait 0 integer time (in ms) how long the next step will take to appear 1.0
expose false true | false | object use the expose feature. object can be an object with CCS properties 1.1
overlayOpacity 0.2 0 - 1 | false the opacity of the overlay. false deactives the overlay 1.1
delayIn 200 integer time (in ms) how long the animationIn methode take 1.0
delayOut 100 integer time (in ms) how long the animationOut methode take 1.0
animationIn 'fadeIn' 'fadeIn' | 'slideDown' | 'show' method used to show the box 1.0
animationOut 'fadeOut' 'fadeOut' | 'slideUp' | 'hide' method used to hide the box 1.0
onBeforeShow function (element) {} callback function callback before the box appeared 1.0
onShow function (element) {} callback function callback after the box appeared 1.0
onBeforeHide function (element) {} callback function callback before the box disappeared 1.0
onHide function (element) {} callback function callback after the box disappeared 1.0
onStep function (element, percentage) {} callback function callback for every step. Check out the jQuery step function for more information 1.0
element 'body' jQuery Selector | jQuery DOM Element The target element for the current step 1.0
goTo null URI The location of the next step. A hash like jTour=NumberOfNextStep gets appended 1.0

not all CSS properties are working properly with the exposure object

The API


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

 

Examples


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!

F.A.Q.


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';
   }
});

 

Changelog


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

 

Sources and Credits


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

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 Birsakrevaxarts.com