Abraham

Guide your users in the one true path.

Abraham injects dynamically-generated Shepherd.js code into your Rails application whenever a user should see a guided tour. Skip a tour, and we'll try again next time; complete a tour, and it won't show up again.

• Define tour content with simple YAML files, in any/many languages.
• Organize tours by controller and action.
• Plays nicely with Turbolinks.

Requirements

Abraham needs to know the current user to track tour views, e.g. current_user from Devise.

Installation

Add Abraham to your Gemfile:

gem 'abraham'

Then run:

$ bundle install
$ rails generate abraham:install

Require Shepherd.js in app/assets/javascripts/application.js

//= require shepherd.js.js

Require a Shepherd.js CSS theme in app/assets/stylesheets/application.scss

//= require "shepherd.js/dist/css/shepherd-theme-default"

Shepherd.js provides the following themes:

• shepherd-theme-arrows
• shepherd-theme-arrows-fix
• shepherd-theme-arrows-plain-buttons
• shepherd-theme-dark
• shepherd-theme-default
• shepherd-theme-square
• shepherd-theme-square-dark

Update config/abraham.yml if you choose a different theme:

defaults: &defaults
  :default_theme: 'shepherd-theme-arrows'

Tell Abraham where to insert its generated JavaScript in app/views/layouts/application.html.erb, just before the closing body tag:

<%= abraham_tour %>
</body>
</html>

Defining your tours

Define your tours in the config/tours directory. Its directory structure should mirror your application's controllers, and the tour files should mirror your actions/views.

config/
└── tours/
    └── blog/
    │   ├── show.en.yml
    │   └── show.es.yml    
    └── articles/
        ├── index.en.yml
        ├── index.es.yml
        ├── show.en.yml
        └── show.es.yml

NB: You must specify a locale in the filename, even if you're only supporting one language.

Tour content

A tour is composed of a series of steps. A step may have a title and must have a description. You may attach a step to a particular element on the page, and place the callout to the left, right, top, or bottom.

intro:
  steps:
    1:
      text: "Welcome to your dashboard! This is where we'll highlight key information to manage your day."
    2:
      title: "Events"
      text: "If you're participating in any events today, we'll show that here."
      attachTo:
        element: ".dashboard-events"
        placement: "right"
    3:
      title: "Search"
      text: "You can find anything else by using the search bar."
      attachTo:
        element: ".navbar-primary form"
        placement: "bottom"

Abraham takes care of which buttons should appear with each step:

• "Later" and "Continue" buttons on the first step
• "Exit" and "Next" buttons on intermediate steps
• "Done" button on the last step

Testing your tours

Abraham loads tour definitions once when you start your server. Restart your server to see tour changes.