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, thedefaults
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 astext
orbuttons
, 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’sbind()
method.off(event, handler)
– Unbinds an event.
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 atext
, additionalclasses
to be added to it, and anaction
to be performed when clicking the button.
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
What is Application Shepherd and how does it differ from Shepherd.js?
Application Shepherd is a JavaScript library that guides users through your app. It’s different from Shepherd.js in that it’s designed to be more user-friendly and easier to implement. While Shepherd.js is a powerful tool, it requires a deeper understanding of JavaScript to use effectively. Application Shepherd, on the other hand, is designed to be accessible to developers of all skill levels, with a simple API and clear documentation.
How do I install Application Shepherd?
Installing Application Shepherd is straightforward. You can install it via npm using the command npm install application-shepherd
. Once installed, you can import it into your project using import Shepherd from 'application-shepherd'
.
Can I customize the look and feel of the guides created with Application Shepherd?
Yes, Application Shepherd allows for extensive customization. You can change the color, size, position, and more of the guide elements. This allows you to create guides that match the look and feel of your app, providing a seamless user experience.
How does Application Shepherd handle complex, multi-step guides?
Application Shepherd is designed to handle complex guides with ease. You can create multi-step guides that guide users through a series of tasks. Each step can have its own text, position, and actions, allowing you to create detailed, interactive guides.
Can I use Application Shepherd with my existing codebase?
Absolutely. Application Shepherd is designed to be easy to integrate with existing codebases. It’s a standalone library, so it doesn’t require any specific framework or technology to use. You can simply import it into your project and start creating guides.
How does Application Shepherd compare to other user guide libraries?
Application Shepherd stands out for its ease of use and flexibility. While other libraries may require more technical knowledge to use effectively, Application Shepherd is designed to be accessible to developers of all skill levels. It also offers extensive customization options, allowing you to create guides that match the look and feel of your app.
Is Application Shepherd mobile-friendly?
Yes, Application Shepherd is designed to work well on both desktop and mobile devices. The guides automatically adjust to fit the screen size, ensuring a great user experience on all devices.
Can I use Application Shepherd for onboarding new users?
Yes, Application Shepherd is an excellent tool for onboarding new users. You can create detailed, step-by-step guides that walk new users through your app, helping them understand how to use it effectively.
How do I update or modify guides created with Application Shepherd?
Updating or modifying guides is easy with Application Shepherd. You can simply change the properties of the guide steps in your code, and the changes will be reflected in the guide. This allows you to keep your guides up-to-date as your app evolves.
Is there a community or support network for Application Shepherd?
While there isn’t a dedicated community or support network for Application Shepherd, you can find help and advice on general JavaScript and web development forums and communities. The documentation for Application Shepherd is also a great resource for learning how to use the library effectively.
Shaumik is a data analyst by day, and a comic book enthusiast by night (or maybe, he's Batman?) Shaumik has been writing tutorials and creating screencasts for over five years. When not working, he's busy automating mundane daily tasks through meticulously written scripts!