Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/actmd/abraham
Trackable application tours for Rails with i18n support
https://github.com/actmd/abraham
i18n rails-engine shepherd tour
Last synced: about 1 month ago
JSON representation
Trackable application tours for Rails with i18n support
- Host: GitHub
- URL: https://github.com/actmd/abraham
- Owner: actmd
- License: mit
- Created: 2016-11-17T18:19:59.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2023-10-26T17:06:00.000Z (about 1 year ago)
- Last Synced: 2024-04-14T02:18:26.139Z (8 months ago)
- Topics: i18n, rails-engine, shepherd, tour
- Language: Ruby
- Size: 276 KB
- Stars: 121
- Watchers: 17
- Forks: 42
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Abraham
[](https://travis-ci.com/actmd/abraham)
_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).
* Define tour content with simple YAML files, in any/many languages.
* Organize tours by controller and action.
* Trigger tours automatically on page load or manually via JavaScript method.
* Built with the [Shepherd JS](https://shepherdjs.dev/) library. Plays nicely with Turbolinks.
* Ships with two basic CSS themes (default & dark) — or write your own
## Requirements
* Abraham needs to know the current user to track tour views, e.g. `current_user` from Devise.
* If you are using a different method to identify who is currently logged in, you can, for example, add an alias to make it work. Assuming you have a method `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`.
* Abraham is tested on Rails 5.2, 6.0, and 6.1
## Installation
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](https://shepherdjs.dev/docs/tutorial-03-styling.html) based on Shepherd's [default CSS](https://github.com/shipshapecode/shepherd/releases/download/v6.0.0-beta.1/shepherd.css).
Tell Abraham where to insert its generated JavaScript in `app/views/layouts/application.html.erb`, just before the closing `body` tag:
```erb
<%= abraham_tour %>