{"id":13878340,"url":"https://github.com/actmd/abraham","last_synced_at":"2025-04-09T13:03:07.989Z","repository":{"id":13456322,"uuid":"74054873","full_name":"actmd/abraham","owner":"actmd","description":"Trackable application tours for Rails with i18n support","archived":false,"fork":false,"pushed_at":"2023-10-26T17:06:00.000Z","size":283,"stargazers_count":121,"open_issues_count":12,"forks_count":42,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-04-14T02:18:26.139Z","etag":null,"topics":["i18n","rails-engine","shepherd","tour"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/actmd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-17T18:19:59.000Z","updated_at":"2024-08-06T08:46:53.786Z","dependencies_parsed_at":"2022-09-16T00:12:54.079Z","dependency_job_id":"26b96f1c-73a3-482a-a6c0-8b3deb2f3818","html_url":"https://github.com/actmd/abraham","commit_stats":{"total_commits":58,"total_committers":14,"mean_commits":4.142857142857143,"dds":0.4655172413793104,"last_synced_commit":"75f4e69dc881ffd9b22b27667dfd46e66983bb10"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/actmd%2Fabraham","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/actmd%2Fabraham/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/actmd%2Fabraham/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/actmd%2Fabraham/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/actmd","download_url":"https://codeload.github.com/actmd/abraham/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248045230,"owners_count":21038553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["i18n","rails-engine","shepherd","tour"],"created_at":"2024-08-06T08:01:46.772Z","updated_at":"2025-04-09T13:03:07.969Z","avatar_url":"https://github.com/actmd.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Abraham\n\n[![Build Status](https://travis-ci.com/actmd/abraham.svg?branch=master)](https://travis-ci.com/actmd/abraham)\n\n_Guide your users in the one true path._\n\n![Watercolor Sheep](https://upload.wikimedia.org/wikipedia/commons/e/e4/Watercolor_Sheep_Drawing.jpg)\n\nAbraham 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).\n\n* Define tour content with simple YAML files, in any/many languages.\n* Organize tours by controller and action.\n* Trigger tours automatically on page load or manually via JavaScript method.\n* Built with the [Shepherd JS](https://shepherdjs.dev/) library. Plays nicely with Turbolinks.\n* Ships with two basic CSS themes (default \u0026 dark) — or write your own\n\n## Requirements\n\n* Abraham needs to know the current user to track tour views, e.g. `current_user` from Devise.\n  * 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`.\n* Abraham is tested on Rails 5.2, 6.0, and 6.1\n\n## Installation\n\nAdd `abraham` to your Gemfile:\n\n```\ngem 'abraham'\n\n```\n\nInstall the gem and run the installer:\n\n```\n$ bundle install\n$ rails generate abraham:install\n$ rails db:migrate\n```\n\nInstall the JavaScript dependencies:\n\n```\n$ yarn add js-cookie@^2.2.0 shepherd.js@^6.0.0-beta\n```\n\nRequire `abraham` in `app/assets/javascripts/application.js`\n\n```\n//= require abraham\n```\n\nRequire a CSS theme in `app/assets/stylesheets/application.scss`\n\n```\n*= require abraham/theme-default\n```\n\nAbraham provides the following themes:\n\n- `theme-default`\n- `theme-dark`\n\nUpdate `config/abraham.yml` if you choose a different theme:\n\n```\ndefaults: \u0026defaults\n  :tour_options: '{ defaultStepOptions: { classes: \"theme-dark\" } }'\n```\n\nYou 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).\n\nTell Abraham where to insert its generated JavaScript in `app/views/layouts/application.html.erb`, just before the closing `body` tag:\n\n```erb\n\u003c%= abraham_tour %\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Defining your tours\n\nDefine 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.)\n\n```\nconfig/\n└── tours/\n    ├── admin/\n    │   └── articles/  \n    │       └── edit.en.yml    \n    ├── blog/\n    │   ├── show.en.yml\n    │   └── show.es.yml    \n    └── articles/\n        ├── index.en.yml\n        ├── index.es.yml\n        ├── show.en.yml\n        └── show.es.yml\n```\n\nFor example, per above, when a Spanish-speaking user visits `/articles/`, they'll see the tours defined by `config/tours/articles/index.es.yml`.\n\n(Note: You must specify a locale in the filename, even if you're only supporting one language.)\n\n### Tour content\n\nWithin 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.\n\nIn this example, we define a tour called \"intro\" with 3 steps:\n\n```yaml\nintro:\n  steps:\n    1:\n      text: \"Welcome to your dashboard! This is where we'll highlight key information to manage your day.\"\n    2:\n      title: \"Events\"\n      text: \"If you're participating in any events today, we'll show that here.\"\n      attachTo:\n        element: \".dashboard-events\"\n        placement: \"right\"\n    3:\n      title: \"Search\"\n      text: \"You can find anything else by using the search bar.\"\n      attachTo:\n        element: \".navbar-primary form\"\n        placement: \"bottom\"\n```\n\nAbraham takes care of which buttons should appear with each step:\n\n* \"Later\" and \"Continue\" buttons on the first step\n* \"Exit\" and \"Next\" buttons on intermediate steps\n* \"Done\" button on the last step\n\nSee below for how to define custom buttons.\n\nWhen you specify an `attachTo` element, use the `placement` option to choose where the callout should appear relative to that element:\n\n* `bottom` / `bottom center`\n* `bottom left`\n* `bottom right`\n* `center` / `middle` / `middle center`\n* `left` / `middle left`\n* `right` / `middle right`\n* `top` / `top center`\n* `top left`\n* `top right`\n\nAbraham tries to be helpful when your tour steps attach to page elements that are missing:\n\n* If your first step is attached to a particular element, and that element is not present on the page, the tour won't start. ([#28](https://github.com/actmd/abraham/issues/28))\n* If your tour has an intermediate step attached to a missing element, Abraham will skip that step and automatically show the next. ([#6](https://github.com/actmd/abraham/issues/6))\n\n### Automatic vs. manual tours\n\nBy default, Abraham will automatically start a tour that the current user hasn't seen yet.\nYou can instead define a tour to be triggered manually using the `trigger` option:\n\n```yml\nwalkthrough:\n  trigger: \"manual\"\n  steps:\n    1:\n      text: \"This walkthrough will show you how to...\"\n```\n\nThis tour will not start automatically; instead, use the `Abraham.startTour` method with the tour name:\n\n```\n\u003cbutton id=\"startTour\"\u003eStart tour\u003c/button\u003e\n\n\u003cscript\u003e\n  document.querySelector(\"#startTour\").addEventListener(\"click\", function() {\n    Abraham.startTour(\"walkthrough\"));\n  });\n\u003c/script\u003e\n```\n\n...or if you happen to use jQuery:\n\n```\n\u003cscript\u003e\n  $(\"#startTour\").on(\"click\", function() { Abraham.startTour('walkthrough'); })\n\u003c/script\u003e\n```\n\n### Custom buttons\n\nYou can define custom buttons in a step like so:\n\n```\nmy_tour:\n  steps:\n    1:\n      text: \"Welcome to my custom button tour\"\n      buttons:\n        1:\n          text: 'Show this to me later'\n          action: 'cancel'\n          classes: 'custom-button shepherd-button-secondary'\n        2:\n          text: 'Finish now'\n          action: 'complete'\n          classes: 'custom-button'\n```\n\n* `action` is one of the Shepherd tour method names, i.e. `cancel`, `next`, or `complete`\n* `classes` are the CSS class names you want applied to the button\n\n### Flipper integration\n\nIf you have [Flipper](https://github.com/jnunemaker/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.\n\n```yml\nwalkthrough:\n  flipper_key: \"name_of_flipper\"\n  steps:\n    1:\n      text: \"This walkthrough will show you how to...\"\n```\n\nIf 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\".\n\n```yml\nwalkthrough:\n  flipper_key: \"name_of_flipper\"\n  flipper_activation: \"disabled\"\n  steps:\n    1:\n      text: \"This walkthrough will show you how to...\"\n```\n\n### Testing your tours\n\nAbraham loads tour definitions once when you start your server. Restart your server to see tour changes.\n\nIf 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.\n\n```\nRails.application.configure do\n  config.abraham.tours = {}\nend\n```\n\n## Full example\n\nWe provide a [small example app](https://github.com/actmd/abraham-example) that implements Abraham, so you can see it in action.\n\n## Upgrading\n\n### From version 2.3.0 or earlier\n\nAbraham 2.4.0 introduced an updated initializer that supports controllers organized into modules.\nRerun the generator with these options to replace the old initializer:\n\n```\n$ rails generate abraham:install --skip-migration --skip-config\n```\n\n### From version 1\n\nAbraham v1 was built using Shepherd 1.8, v2 now uses Shepherd 6 – quite a jump, yes.\n\nIf you were using Abraham v1, you'll want to take the following steps to upgrade:\n\n1. Update your gem to the latest version\n1. Fix your yarn dependencies to use the right versions\n1. Shepherd no longer provides a set of themes. Abraham maintains two of the legacy themes: default and dark. You'll want to choose one of those or migrate your theme to the new Shepherd structure.\n1. Abraham now exposes the entire Shepherd configuration object, so your `abraham.yml` file should now fully define the `tour_options` value instead of `default_theme`\n1. There's been a slight change to `initializers/abraham.rb`. Replace yours with [the latest](https://github.com/actmd/abraham/blob/master/lib/generators/abraham/templates/initializer.rb).\n\nIf you have any trouble at all, please [submit an issue](https://github.com/actmd/abraham/issues) for assistance!\n\n## Contributing\n\nContributions are welcome!\n\nCreate a feature branch (using git-flow) and submit as a pull request (with a base branch of `develop`).\n\nEveryone interacting in Abraham's codebase, issue tracker, etc. is expected to follow the [Contributor Covenent Code of Conduct](https://www.contributor-covenant.org/version/1/4/code-of-conduct).\n\n### Getting started with the source code\n\nAbraham uses `rvm` with a gemset to ensure the appropriate version of Ruby and its dependencies. Make sure that's installed before you get started.\n\n```\n~ git clone git@github.com:actmd/abraham.git\nCloning into 'abraham'...\n~ cd abraham\nruby-2.5.3 - #gemset created /Users/jon/.rvm/gems/ruby-2.5.3@abraham\nruby-2.5.3 - #generating abraham wrappers - please wait\n~ bundle install\nBundle complete! 13 Gemfile dependencies, 73 gems now installed.\nUse `bundle info [gemname]` to see where a bundled gem is installed.\n~ yarn install\n```\n\n### Testing\n\n#### Testing locally\n\nThis Rails engine contains a test app called `dummy` with controller and system tests. They'll all get run with `rails t`.\n\nPlease 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.\n\nFinal testing should be done in a standalone Rails app, following the README instructions.\n\nTo install the `abraham` gem with a local path:\n\n```\ngem 'abraham', path: '~/Workspace/abraham'\n```\n\n#### Automated testing\n\nWe use GitHub Actions to automatically test this engine with Rails 5.2, 6.0, and 6.1.\n\n### Releasing\n\nCreate a git-flow release:\n\n```\n$ git flow release start VERSION_NUMBER\n```\n\nEdit `lib/abraham/version.rb` and increase the version number.\n\nBuild the gem and push to Rubygems:\n\n```\n$ rake build\n$ gem push pkg/abraham-VERSION_NUMBER.gem\n```\n\nFinish the git-flow release and push to GitHub:\n\n```\n$ git flow release finish\n$ git push origin develop\n$ git push origin master\n$ git push --tags\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Factmd%2Fabraham","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Factmd%2Fabraham","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Factmd%2Fabraham/lists"}