Introducing Your Application with Shepherd

As a web developer, you probably realize that creating an application is often the easy part – presenting it to the world is an uphill task in itself. Some prefer creating presentations, some others make videos. Wouldn’t it be nice if you had something to help you walk your users through your app? Enter Shepherd, by HubSpot. Shepherd is a simple JavaScript library which helps you guide your users through a tour of your application. It helps you direct your users to the right place, just like a shepherd takes care of his flock of sheep. There are other libraries for this purpose too, but the reason I prefer Shepherd is that it doesn’t have any dependencies. It also has support for CoffeeScript, though we will only be exploring JavaScript here.

Getting Started

Shepherd is open source and its code can be found on GitHub. The demo of Shepherd is also available on Hubspot. Let’s get started. For the impatient, here is the basic code to get started. This creates a one step tour of your application. This binds the dialog to the bottom of the element matched by the selector #id_selector.

var tour = new Shepherd.Tour({
  defaults: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

tour.addStep('myStep', {
  title: 'Hi there!',
  text: 'This would help you get started with this application!',
  attachTo: '#id_selector bottom',
  classes: 'shepherd shepherd-open shepherd-theme-arrows shepherd-transparent-text',
  buttons: [
    {
      text: 'Exit',
      classes: 'shepherd-button-secondary',
      action: function() {
        return tour.hide();
      }
    }
  ]
});

Breaking Shepherd Down

Now that you’ve got the simple code running, let’s break the steps into pieces that we can understand.

Includes

You need to include the single Shepherd JavaScript file. Shepherd also comes with a default theme, contained in a CSS file.

<link type="text/css" rel="stylesheet" href="css/shepherd-theme-arrows.css" />
<script type="text/javascript" src="./shepherd.min.js"></script>

Initialize Shepherd

The following code sample shows how a tour is created via JavaScript. Since you will be adding steps to your tour shortly, the defaults option in the initialization adds those options to all your steps, unless you override them:

tour = new Shepherd.Tour({
  defaults: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

Creating Steps

Let’s check out that “getting started” code again. Here is the code that initiates a single step of the tour:

tour.addStep('myStep', {
  title: 'Hi there!',
  text: 'This would help you get started with this application!',
  attachTo: '#id_selector bottom',
  classes: 'shepherd shepherd-open shepherd-theme-arrows shepherd-transparent-text',
  buttons: [
    {
      text: 'Exit',
      classes: 'shepherd-button-secondary',
      action: function() {
        return tour.hide();
      }
    }
  ]
});

You can attach an additional button if you plan to have multiple steps. The following is an example of how to use buttons if you have two steps:

tour.addStep('step1', {
  ...
  buttons: [
    {
      text: 'Exit',
      classes: 'shepherd-button-secondary',
      action: function() {
        return tour.hide();
      }
    }, {
      text: 'Next',
      action: tour.next,
      classes: 'shepherd-button-example-primary'
    }
  ]
});

tour.addStep('step2', {
  ...
  buttons: [
    {
      text: 'Back',
      action: tour.back,
      classes: 'shepherd-button-example-primary'
    }, {
      text: 'Exit',
      classes: 'shepherd-button-secondary',
      action: function() {
        return tour.hide();
      }
    } 
  ]
});

Start the Tour

After setting the tour up, all that is left is to start it up!

tour.start();

The API

Shepherd provides an extensive API, as well as documentation that explains its behavior. Here we’ll go through some useful calls.

Tour Instances

First, create the tour as shown below.

myTour = new Shepherd.Tour({ options })

Now, we are going to see how we can work with this instance. steps and defaults are the options of the tour instance. Its methods are described below.

• addStep(id, options) – As we saw above, a step is created by assigning an ID to it, then adding options such as text or buttons, which are described later.
• getById(id) – This method is used to select any particular step by its ID.
• show(id) – Show a particular step by ID.
• on(event, handler) – Binds an event to your tour. This is similar to jQuery’s bind() method.
• off(event, handler) – Unbinds an event.

A tour instance also has events like start, complete, show, and hide.

Steps

Although we have added steps before, let’s take a closer look. The following list describes the options you can define.

• title– You may or may not apply a title.
• text – The text to be shown in the step.
• attachTo – This has two parts: the selector of the element where the step is to be attached, and the position to attach the step to (i.e. #id_selector bottom).
• classes – Extra classes to add to your dialog. This depends on the theme you are using.
• buttons – The list of buttons to be shown. Each button has a text, additional classes to be added to it, and an action to be performed when clicking the button.

There are various methods that can be used to make your task easier. Here are some of the useful ones:

• show() – Show a step.
• hide() – Hide a step.
• cancel() – Hide step and cancel the tour.
• complete() – Hide step and complete the tour.
• destroy() – Destroys a step.
• on(event, handler) – Binds an event.
• on(event, handler) – Unbinds an event.

Conclusion

Although Shepherd looks pretty promising, one hiccup I have noticed is the browser support of IE 9+. But if you don’t plan to support old browsers, then give it a try. You can find a live demo based on this article’s code on GitHub. The demo can be further modified. You could try binding event handlers for the arrow keys to the Shepherd navigation. You could also make CSS classes and attach them to different elements to shift focus from one element to another.

Frequently Asked Questions (FAQs) about Application Shepherd