Guide your users in the one true path.
Abraham makes it easy to show guided tours to users of your Rails application. When Abraham shows a tour, it keeps track of whether the user has completed it (so it doesn't get shown again) or dismissed it for later (so it reappears in a future user session).
current_user
from Devise.
current_foo
to identify your currenly logged-in user, you can add alias_method 'current_user', 'current_foo'
in the place you define current_foo
.Add abraham
to your Gemfile:
gem 'abraham'
Install the gem and run the installer:
$ bundle install
$ rails generate abraham:install
$ rails db:migrate
Install the JavaScript dependencies:
$ yarn add js-cookie@^2.2.0 shepherd.js@^6.0.0-beta
Require abraham
in app/assets/javascripts/application.js
//= require abraham
Require a CSS theme in app/assets/stylesheets/application.scss
*= require abraham/theme-default
Abraham provides the following themes:
theme-default
theme-dark
Update config/abraham.yml
if you choose a different theme:
defaults: &defaults
:tour_options: '{ defaultStepOptions: { classes: "theme-dark" } }'
You can also write your own Shepherd theme based on Shepherd's default CSS.
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>
Define your tours in the config/tours
directory corresponding to the views defined in your application. Its directory structure mirrors your application's controllers, and the tour files mirror your actions/views. (As of version 2.4.0, Abraham respects controllers organized into modules.)
config/
└── tours/
├── admin/
│ └── articles/
│ └── edit.en.yml
├── blog/
│ ├── show.en.yml
│ └── show.es.yml
└── articles/
├── index.en.yml
├── index.es.yml
├── show.en.yml
└── show.es.yml
For example, per above, when a Spanish-speaking user visits /articles/
, they'll see the tours defined by config/tours/articles/index.es.yml
.
(Note: You must specify a locale in the filename, even if you're only supporting one language.)
Within a tour file, each tour is composed of a series of steps. A step may have a title
and must have text
. You may attach a step to a particular element on the page, and place the callout in a particular position.
In this example, we define a tour called "intro" with 3 steps:
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:
See below for how to define custom buttons.
When you specify an attachTo
element, use the placement
option to choose where the callout should appear relative to that element:
bottom
/ bottom center
bottom left
bottom right
center
/ middle
/ middle center
left
/ middle left
right
/ middle right
top
/ top center
top left
top right
Abraham tries to be helpful when your tour steps attach to page elements that are missing:
By default, Abraham will automatically start a tour that the current user hasn't seen yet.
You can instead define a tour to be triggered manually using the trigger
option:
walkthrough:
trigger: "manual"
steps:
1:
text: "This walkthrough will show you how to..."
This tour will not start automatically; instead, use the Abraham.startTour
method with the tour name:
<button id="startTour">Start tour</button>
<script>
document.querySelector("#startTour").addEventListener("click", function() {
Abraham.startTour("walkthrough"));
});
</script>
...or if you happen to use jQuery:
<script>
$("#startTour").on("click", function() { Abraham.startTour('walkthrough'); })
</script>
You can define custom buttons in a step like so:
my_tour:
steps:
1:
text: "Welcome to my custom button tour"
buttons:
1:
text: 'Show this to me later'
action: 'cancel'
classes: 'custom-button shepherd-button-secondary'
2:
text: 'Finish now'
action: 'complete'
classes: 'custom-button'
action
is one of the Shepherd tour method names, i.e. cancel
, next
, or complete
classes
are the CSS class names you want applied to the buttonIf you have Flipper installed as a dependency in your project you will be able to enable or disable tours based on a flipper using the flipper_key
option. This will automatically enable a tour when this flipper is active and disable it when it's inactive.
walkthrough:
flipper_key: "name_of_flipper"
steps:
1:
text: "This walkthrough will show you how to..."
If you would like to disable a tour when a flipper is active you may couple the flipper_key
option with the flipper_activation
option. flipper_activation
supports "enabled" or "disabled" as options. If you enter something other than "enabled" or "disabled" it will use the default, which is "enabled".
walkthrough:
flipper_key: "name_of_flipper"
flipper_activation: "disabled"
steps:
1:
text: "This walkthrough will show you how to..."
Abraham loads tour definitions once when you start your server. Restart your server to see tour changes.
If you'd like to run JavaScript integrations tests without the Abraham tours getting in the way, clear the Abraham configuration in your test helper, e.g.
Rails.application.configure do
config.abraham.tours = {}
end
We provide a small example app that implements Abraham, so you can see it in action.
Abraham 2.4.0 introduced an updated initializer that supports controllers organized into modules. Rerun the generator with these options to replace the old initializer:
$ rails generate abraham:install --skip-migration --skip-config
Abraham v1 was built using Shepherd 1.8, v2 now uses Shepherd 6 – quite a jump, yes.
If you were using Abraham v1, you'll want to take the following steps to upgrade:
abraham.yml
file should now fully define the tour_options
value instead of default_theme
initializers/abraham.rb
. Replace yours with the latest.If you have any trouble at all, please submit an issue for assistance!
Contributions are welcome!
Create a feature branch (using git-flow) and submit as a pull request (with a base branch of develop
).
Everyone interacting in Abraham's codebase, issue tracker, etc. is expected to follow the Contributor Covenent Code of Conduct.
Abraham uses rvm
with a gemset to ensure the appropriate version of Ruby and its dependencies. Make sure that's installed before you get started.
~ git clone git@github.com:actmd/abraham.git
Cloning into 'abraham'...
~ cd abraham
ruby-2.5.3 - #gemset created /Users/jon/.rvm/gems/ruby-2.5.3@abraham
ruby-2.5.3 - #generating abraham wrappers - please wait
~ bundle install
Bundle complete! 13 Gemfile dependencies, 73 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
~ yarn install
This Rails engine contains a test app called dummy
with controller and system tests. They'll all get run with rails t
.
Please note that if you change anything in the lib/generators
folder (i.e. configuration, intializer, migration) you'll need to migrate the dummy
app accordingly.
Final testing should be done in a standalone Rails app, following the README instructions.
To install the abraham
gem with a local path:
gem 'abraham', path: '~/Workspace/abraham'
We use GitHub Actions to automatically test this engine with Rails 5.2, 6.0, and 6.1.
Create a git-flow release:
$ git flow release start VERSION_NUMBER
Edit lib/abraham/version.rb
and increase the version number.
Build the gem and push to Rubygems:
$ rake build
$ gem push pkg/abraham-VERSION_NUMBER.gem
Finish the git-flow release and push to GitHub:
$ git flow release finish
$ git push origin develop
$ git push origin master
$ git push --tags