User-friendly Interactive Guide Plugin - jQuery PageGuide

File Size: 63.6 KB
Views Total: 186
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
User-friendly Interactive Guide Plugin - jQuery PageGuide

A guide for web page elements can be used for several purposes, such as letting the user learn about new features and functions or helping him understand a website's structure. This kind of tool allows users interact with your web page and understand it better.

In this post, you will find a jQuery page guide plugin that allows you to create step-by-step interactive tours to help guide your users around your website. Let's get started.

Features:

  • Adds step number bubbles to each element.
  • Highlights elements when activated.
  • Allows multiple page guides on the same page.
  • Smoothly scroll the page to the activated element (step).
  • Displays a guide slider at the bottom of the page, which allows you to switch between steps in a easy way.

How to use it:

1. Get started by loading the latest jQuery PageGuide plugin's files in the document.

<link rel="stylesheet" href="/path/to/dist/css/pageguide.min.css" />
<script src="/path/to/cdn/jquery.min.js"></script>
<script src="/path/to/dist/js/pageguide.min.js"></script>

2. Create a list of steps for the guide. The data-tourtarget attribute should contain the selector for the element to which you want to attach this pageguide step. You can use the following classes to indicate where each number bubble should be positioned.

  • tlypageguide_left
  • tlypageguide_right
  • tlypageguide_top
  • tlypageguide_bottom
<div class="first_element_to_target">
  Element 1
</div>
<div id="second_element_to_target">
  Element 2
</div>
<div class="third_element_to_target">
  Element 3
</div>
...
<ul id="tlyPageGuide" data-tourtitle="Check out these elements">
  <li class="tlypageguide_left" data-tourtarget=".first_element_to_target">
    Element 1 Description
  </li>
  <li class="tlypageguide_right" data-tourtarget="#second_element_to_target">
    Element 2 Description
  </li>
  <li class="tlypageguide_left" data-tourtarget=".third_element_to_target">
    Element 3 Description
  </li>
  ...
</ul>

3. Create a welcome popup for the guide.

<div class="tlyPageGuideWelcome">
  <p>Welcome to my new page! pageguide is here to help you learn more.</p>
  <button class="tlypageguide_start">let's go</button>
  <button class="tlypageguide_ignore">not now</button>
  <button class="tlypageguide_dismiss">got it, thanks</button>
</div>

4. Initialize the PageGuide plugin on document ready. That's it.

jQuery(document).ready(function() {
  var pageguide = tl.pg.init();
});

5. All default plugins to customize the guide.

tl.pg.init({

  // Whether or not to focus on the first visible item immediately on PG open
  'auto_show_first': true,

  // The CSS selector for the loading element. 
  // pageguide will wait until this element is no longer visible starting up.
  'loading_selector' : '#loading',

  // Optional callback for tracking user interactions with pageguide.  
  // Should be a function taking a single parameter indicating the name of the interaction.
  'track_events_cb': function() { return; },

  // Optional callback to enlight or adapt interface depending on current documented element. 
  // Should be a function taking 2 parameters, current and previous data-tourtarget selectors.
  'handle_doc_switch': null,

  // Optional id for toggling pageguide.
  // If not specified then the default button is used.
  'custom_open_button': null,

  // Visible caption
  'pg_caption' : 'page guide',

  // Tour title
  'tourtitle': 'Open Page Guide for help',

  // Check whether or not the welcome message has been dismissed. 
  // Must return true or false. 
  // This function should check against whatever state change is made in dismiss_welcome.
  'check_welcome_dismissed': function () {
    var key = 'tlypageguide_welcome_shown_' + tl.pg.hashUrl();
    // first, try to use localStorage
    try {
      if (localStorage.getItem(key)) {
        return true;
      }
    // cookie fallback for older browsers
    } catch(e) {
      if (document.cookie.indexOf(key) > -1) {
        return true;
      }
    }
    return false;
  },

  // Permanently dismiss the welcome message, corresponding to check_welcome_dismissed.
  'dismiss_welcome': function () {
    var key = 'tlypageguide_welcome_shown_' + tl.pg.hashUrl();
    try {
      localStorage.setItem(key, true);
    } catch(e) {
      var exp = new Date();
      exp.setDate(exp.getDate() + 365);
      document.cookie = (key + '=true; expires=' + exp.toUTCString());
    }
  },

  // A function to run once the pageguide ready event fires.
  'ready_callback': null,

  // Specify whether or not to provide a fallback for css pointer-events in browsers that do not support it
  'pointer_fallback': true,

  // The css z-index to apply to the tlypageguide_shadow overlay elements
  'default_zindex': 100,

  // Selector for the ul element whose steps you wish to use in this particular pageguide object
  'steps_element': '#tlyPageGuide',

  // If set to true, pageguide will run a timer to constantly monitor the DOM for changes in the target elements and  adjust the pageguide display (bubbles, overlays, etc) accordingly. 
  // The timer will only run while pageguide is open.
  // Useful for single-page or heavily dynamic apps where pageguide steps or visible DOM elements can change often.
  'auto_refresh': false,

  // Similar to auto_refresh, welcome_refresh enables a timer to monitor the DOM for new .tlyPageGuideWelcome elements. 
  // This is useful if your welcome element isn't loaded immediately, or if you want to show different welcome elements on different pages.
  // The timer will run constantly, whether or not the pageguide is open, so enable at your discretion.
  'refresh_welcome': false,

  // How often to poll the DOM for changes.
  'refresh_interval': 500

});

This awesome jQuery plugin is developed by tracelytics. For more Advanced Usages, please check the demo page or visit the official website.