Introducing Your Application with Shepherd

Key Takeaways

• Shepherd, developed by HubSpot, is a simple JavaScript library that aids in guiding users through an application tour, making the process of introducing an application to users more efficient and interactive.
• The library is open-source and doesn’t have any dependencies, making it a preferred choice for developers. It allows for the creation of steps, each with its own text, position, and actions, and provides an extensive API for customization.
• Despite its promising features, Shepherd has limited browser support, specifically for IE 9 . However, it can be a valuable tool for developers not planning to support older browsers. It also offers a simple API and clear documentation, making it accessible to developers of all skill levels.

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.

<span>var tour = new Shepherd<span>.Tour</span>({
</span>  <span>defaults: {
</span>    <span>classes: 'shepherd-theme-arrows',
</span>    <span>scrollTo: true
</span>  <span>}
</span><span>});
</span>
tour<span>.addStep('myStep', {
</span>  <span>title: 'Hi there!',
</span>  <span>text: 'This would help you get started with this application!',
</span>  <span>attachTo: '#id_selector bottom',
</span>  <span>classes: 'shepherd shepherd-open shepherd-theme-arrows shepherd-transparent-text',
</span>  <span>buttons: [
</span>    <span>{
</span>      <span>text: 'Exit',
</span>      <span>classes: 'shepherd-button-secondary',
</span>      <span>action: function() {
</span>        <span>return tour.hide();
</span>      <span>}
</span>    <span>}
</span>  <span>]
</span><span>});</span>

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.

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

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 <span>= new Shepherd<span>.Tour</span>({
</span>  <span>defaults: {
</span>    <span>classes: 'shepherd-theme-arrows',
</span>    <span>scrollTo: true
</span>  <span>}
</span><span>});</span>

Creating Steps

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

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

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<span>.addStep('step1', {
</span>  <span>...
</span>  <span>buttons: [
</span>    <span>{
</span>      <span>text: 'Exit',
</span>      <span>classes: 'shepherd-button-secondary',
</span>      <span>action: function() {
</span>        <span>return tour.hide();
</span>      <span>}
</span>    <span>}, {
</span>      <span>text: 'Next',
</span>      <span>action: tour.next,
</span>      <span>classes: 'shepherd-button-example-primary'
</span>    <span>}
</span>  <span>]
</span><span>});
</span>
tour<span>.addStep('step2', {
</span>  <span>...
</span>  <span>buttons: [
</span>    <span>{
</span>      <span>text: 'Back',
</span>      <span>action: tour.back,
</span>      <span>classes: 'shepherd-button-example-primary'
</span>    <span>}, {
</span>      <span>text: 'Exit',
</span>      <span>classes: 'shepherd-button-secondary',
</span>      <span>action: function() {
</span>        <span>return tour.hide();
</span>      <span>}
</span>    <span>} 
</span>  <span>]
</span><span>});</span>

Start the Tour

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

tour<span>.start();</span>

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 <span>= new Shepherd<span>.Tour</span>({ options })</span>

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

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.

The above is the detailed content of Introducing Your Application with Shepherd. For more information, please follow other related articles on the PHP Chinese website!