jQuery.PageGuide

Brought to you by Sprint.ly, based on a true story by Tracelytics

jQuery.PageGuide is a jQuery plugin for building dynamic, interactive visual guides that help your users get familiar with all the features of your site, without the unsightly clutter of static help text.

It all began as a simple modification of the fantastic Tracelytics pageguide.js, with intent to make it work as a true jQuery plugin. But while rewriting the code, more and more features kept creeping in, and now it's taken on a life of it's own.

You can dynamically load and unload user guides, fine-tune the positioning of each step, and define event handlers on all parts of the guide (including each step individually) to perform actions in concert with the presentation.

And we have more planned, we can't stop the awesome...

Getting Started

Download jQuery.PageGuide (TAR or Github) and put the files somewhere within your project resource path.

Include the CSS tag somewhere in the HEAD of the html:

<head>
  ...
  <link href="/path/to/css/pageguide.css" rel="stylesheet">
  ...
</head>

Include the JS for jQuery and jQuery.PageGuide at the end of the BODY:
```
<body>
  ...
  <script src="/path/to/js/jquery.js"></script>
  <script src="/path/to/js/jquery.pageguide.js"></script>
</body>
```
Heads up! The same jquery.pageguide.js file will also work with browser-based AMD script loaders, like RequireJS.

Create a guide. Guides can be defined in both html, by using ordered lists (OL's), and in JavaScript. Here we're going to build one in JavaScript (the same one that loads by default on this page):

var guide = {
  id: 'jQuery.PageGuide',
  title: 'Take a quick tour of all the possibilities',
  steps: [
    {
      target: '.hero-unit h1',
      content: 'Each step is associated with a "target" element, specified by a CSS selector. jQuery.PageGuide will automatically filter out any steps with targets that are invisible or don\'t exist..',
      direction: 'left'
    }
  ]
}

Then, as soon as you're ready (or as soon as jQuery is ready), load the guide. The friendly little help icon will slide into view at the top right of the page:
```
$(function() {
  // Load the default guide!
  $.pageguide(defaultGuide);
});
```
Heads up! Make sure to place this code somewhere after the script tags you added in step 3.

If you want to swap to a different guide, go right ahead:

// Something different
var guide2 = {...};

$.pageguide('load', guide2);

And when you're done with that guide, make it go away:
```
$.pageguide('unload');
```

Options

The default settings are good enough to get you started, but there are a ton of options to explore. jQuery.PageGuide allows you to configure settings both globally and for individual guides. Setting options globally will effectively modify the defaults, which can also be overriden when loading a guide for settings that apply only while it's loaded. Keep scrolling to find the full list of options.

Setting global options:

These overrides will apply to all guides that are loaded.

During initialization:

// Guide definition, as described above.
var guide = {...};

// Options to override
var options = {
defaultGuide: guide,      // Load this guide as soon as the page is ready
autoAdvanceInterval: 10,  // Advance to the next step after 10 seconds
pulse: false              // Don't show the pulse animation when a new step is selected
...
}

// Initialize the plugin, the options will be merged with the defaults and apply to any guide loaded
$.pageguide(options);

After initialization:

// These options will be merged with the existing options, and apply to any guides that get loaded
$.pageguide('options', {
  pulse: true,              // Turn the pulse effect back on, it's rad
  step: {
    direction: 'right'      // Change the default position of the floating step indicators
  }
});

Setting options for a single guide:

These overrides will only apply to the guide being loaded.

// Guide definition, as described above.
var guide = {...};

// Options to override for this guide only
var options = {
  autoAdvanceInterval: 10,  // Advance through the guide at 10 second intervals
  ...
  step: {
    shadow: false           // Disable the translucent box around the target element
  }
}

// $.pageguide();           // Only necessary if you haven't already initialized the plugin
$.pageguide('load', guide, options);

API Reference

The two main ways to customize and control jQuery.PageGuide are the guide options, and functions to interact with the interface programmatically. Below you'll find the full list of what's available.

Options

Default Settings:

options: {
    defaultGuide: "#pageGuide",
    autoStart: true,
    autoStartDelay: 0,
    autoAdvanceInterval: null,
    loadingSelector: null,
    pulse: true,
    events: {},
    step: {
        direction: 'left',
        margin: {top: 100, bottom: 100},
        shadow: true,
        shadowPadding: '10px',
        zIndex: null,
        arrow: {
            offsetX: 0,
            offsetY: 0
        },
        events: {}
    }
}

Configurable Options:

Name	Default	Possible Values	Description
Guide (options.*)
defaultGuide	none	String selector, jQuery selector, Object guide	CSS selector or guide definition object to load when $.pageguide is initialized without a guide as the first argument.
autoStart	true	true, false	Whether or not to focus on the first visible item immediately on open.
autoStartDelay	0	(int milliseconds)	Add a delay before automatically selecting the first visible item after the guide is opened.
autoAdvanceInterval	null	int seconds	Rotate through the visible steps at a regular interval while the guide is open.
loadingSelector	none	String selector, jQuery selector	The CSS selector for the DOM element used as a loading indicator. PageGuide will wait until this element is no longer visible before starting up.
pulse	true	true, false	Show an animated effect to further highlight the target element whenever a new step is selected. Requires the step shadow to be set to 'true'.
events	{}	Object {init, ready, load, unload, open, close, previous, next, step, resize, click} callback functions)	Convenience wrapper to specify guide-level event handlers. These events are bound on load, and automatically removed when the guide is unloaded.
Step (options.step.*)
direction	'left'	'top', 'right', 'bottom', 'left'	Position of the floating step number indicator in relation to the target element.
margin	{top: 100, bottom: 100}	Object {top, bottom} in px	Minimum distance the target element must be from top or bottom of the viewport. If the element is outside of this margin, the window will scroll to bring the element into view.
shadow	true	true, false	Render a transparent box around the current step's target element.
shadowPadding	'10px'	String padding, int padding	Applied to all sides of the shadow to pad the height and width around the target element.
zIndex	null	int z-index	Force the base z-index of the step, which is used when rendering the floating step number indicator and the shadow. If set to null, the target element's z-index is used. The shadow is rendered at a z-index of base + 1, and the floating step number indicator is base + 2.
arrow	{offsetX: 0, offsetY: 0}	Object {offsetX, offsetY} in px	Additional offset to apply to the floating step indicator to make fine adjustments to positioning.
events	{}	Object {show, hide, select, deselect} callbacks	Convenience wrapper to specify step-level event handlers. These events are bound to the individual step on load, and automatically removed when the guide is unloaded.

Functions

In the spirit of jQuery, all public functions return the jQuery.PageGuide instance, so they're chainable. For example, if you want to open the guide immediately after loading:

$.pageguide('load', guide, { autoAdvanceInterval: 10 }).open();

$.pageguide('options', [options])

Get or set overrides for base options. If the argument is ommitted, an object containing the current options are returned.

@param {Object} [options] Options to override for all Guides

@return {PageGuide}
$.pageguide('guide', [guide])

Get or load a guide. If the argument is ommitted, the currently loaded guide definition is returned.

@param {String|jQuerySelector|Object} [guide] Guide definition to load

@return {Object|PageGuide} Guide definition if function called with no argument, PageGuide instance if options are specified.
$.pageguide('load', guide, [options])

Get or load a guide. If the argument is ommitted, the currently loaded guide definition is returned.

@param {String|jQuerySelector|Object} [guide] Guide definition to load

@param {Object} [options] Override options applied only to this guide

@return {PageGuide}
$.pageguide('unload')

Close and disable the current guide. Removes guide event handlers.

@return {PageGuide}
$.pageguide('open')

Start the guide. If `options.autoStart` is true, the first step will be selected automatically.

@return {PageGuide}
$.pageguide('close')

Stop the guide

@return {PageGuide}
$.pageguide('previous')

Show the visible step prior to the currently selected step.

@return {PageGuide}
$.pageguide('next')

Advance the guide to the next visible step.

@return {PageGuide}
$.pageguide('showStep', newIdx)

Select step by index.

@param {int} newIdx The index (0-based) of the step to select

@param {int} [direction] If negative, the step number in the message field will scroll to the left, if positive it will scroll to the right. If undefined or 0, it will be calculated automatically.

@return {PageGuide}
$.pageguide('isLoaded')

Check if a guide is currently loaded.

@return {Boolean}
$.pageguide('isOpen')

Check if the guide is running.

@return {Boolean}

Examples

Simple Example

This is a basic example of a guide definition in JavaScript just to get your feet wet.

loading...

Try it

Override Default Options

You can customize options when loading a guide, which will be applied only to that guide.

loading...

Try it

Event Listeners

You can add event listeners on any part of a guide. In this example, we'll show an alert when an item is selected.

loading...

Try it

jQuery.PageGuide

Getting Started

Options

Setting global options:

Setting options for a single guide:

API Reference

Options

Default Settings:

Configurable Options:

Functions

$.pageguide('options', [options])

$.pageguide('guide', [guide])

$.pageguide('load', guide, [options])

$.pageguide('unload')

$.pageguide('open')

$.pageguide('close')

$.pageguide('previous')

$.pageguide('next')

$.pageguide('showStep', newIdx)

$.pageguide('isLoaded')

$.pageguide('isOpen')

Examples

Simple Example

Override Default Options

Event Listeners