abraham 2.1.2 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 934942f3a067c17e06029f1095f7abf5b570d5e7b63a8d16601769df4d3300e1
-  data.tar.gz: 2389400109634350208fff528edf7c70577982677f34e8af9ef84dcb49aa9d5a
+  metadata.gz: 025f51bb1380ebbd7c172d43d66b79ca4b68fdb4eb4af6940364fff44b282176
+  data.tar.gz: a791c10896b5f002e1aa5daa8edccd2ec810a4479aeccac4a5d8b28a52795c5d
 SHA512:
-  metadata.gz: ec5c02fcd3b19038b65b9a3af6ce3d84f585c47e465a914021d05a18c340665fb1891fb590fb76b332a05eb5d7e6736e89aba9e854cf94ad0acb921c4cc623ce
-  data.tar.gz: c00a73dfe7269459459fadaa4db889de665ec0601273fa431d94372cf38383e4f0a5c1b5959fbf0a7f5ea681fb149948dadc2ec4670e09941b54356979500274
+  metadata.gz: 4e6f5e3fae2acca16748c5ace7c7fde3436e3aab72604c3e35030d5488ec389fd4903ff53a63dbdc4fe473a554853860a6d6f05e8a126bd49d7ae15f71c573b4
+  data.tar.gz: 816fb772c290eb0504885b2e93f21d952e7322bf87c05ca3332d57c6ff81fb1e5062a93824d5d087b142c05e4efab6af2f01fdbbc12623b9b3740acb82cc4a7d

data/README.md

@@ -6,16 +6,19 @@ _Guide your users in the one true path._
 
 ![Watercolor Sheep](https://upload.wikimedia.org/wikipedia/commons/e/e4/Watercolor_Sheep_Drawing.jpg)
 
-Abraham injects dynamically-generated [Shepherd](https://shepherdjs.dev/) JavaScript 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.
+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.
-* Plays nicely with Turbolinks.
-* Ships with two basic CSS themes (default & dark) -- or write your own
+* 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.
+* 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
 
@@ -37,7 +40,7 @@ $ rails db:migrate
 Install the JavaScript dependencies:
 
 ```
-$ yarn add jquery@^3.4.0 js-cookie@^2.2.0 shepherd.js@^6.0.0-beta
+$ yarn add js-cookie@^2.2.0 shepherd.js@^6.0.0-beta
 ```
 
 Require `abraham` in `app/assets/javascripts/application.js`
@@ -76,12 +79,15 @@ Tell Abraham where to insert its generated JavaScript in `app/views/layouts/appl
 
 ## 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.
+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/
-    └── blog/
+    ├── admin/
+    │   └── articles/  
+    │       └── edit.en.yml    
+    ├── blog/
     │   ├── show.en.yml
     │   └── show.es.yml    
     └── articles/
@@ -91,11 +97,15 @@ config/
         └── show.es.yml
 ```
 
-NB: You must specify a locale in the filename, even if you're only supporting one language.
+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.)
 
 ### 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.
+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:
 
 ```yaml
 intro:
@@ -122,11 +132,81 @@ Abraham takes care of which buttons should appear with each step:
 * "Exit" and "Next" buttons on intermediate steps
 * "Done" button on the last 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:
 
 * 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))
 * 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))
 
+### Automatic vs. manual tours
+
+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:
+
+```yml
+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>
+```
+
+### Custom buttons
+
+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 button
+
 ### Testing your tours
 
 Abraham loads tour definitions once when you start your server. Restart your server to see tour changes.
@@ -141,11 +221,22 @@ end
 
 ## Full example
 
-We provide a [small example app](https://github.com/actmd/abraham-example) that implements abraham, so you can see it in action.
+We provide a [small example app](https://github.com/actmd/abraham-example) that implements Abraham, so you can see it in action.
 
-## Upgrading from version 1
+## Upgrading
 
-Abraham v1 was built using Shepherd 1.8, v2 now uses Shepherd 6 -- quite a jump, yes.
+### From version 2.3.0 or earlier
+
+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
+```
+
+### From version 1
+
+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:
 
@@ -161,10 +252,26 @@ If you have any trouble at all, please [submit an issue](https://github.com/actm
 
 Contributions are welcome!
 
-Create a feature branch (using git-flow) and submit as a pull request.
+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](https://www.contributor-covenant.org/version/1/4/code-of-conduct).
 
+### Getting started with the source code
+
+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
+```
+
 ### Testing
 
 #### Testing locally
@@ -183,7 +290,7 @@ gem 'abraham', path: '~/Workspace/abraham'
 
 #### Automated testing
 
-We use TravisCI to automatically test this engine with Rails 5.1, 5.2, and 6.0. For test history, venture over to [TravisCI](https://travis-ci.com/actmd/abraham).
+We use GitHub Actions to automatically test this engine with Rails 5.2, 6.0, and 6.1.
 
 ### Releasing
 

data/Rakefile

@@ -26,10 +26,10 @@ require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "lib"
   t.libs << "test"
   t.pattern = "test/**/*_test.rb"
   t.verbose = false
+  t.warning = false 
 end
 
 task default: :test

data/app/assets/javascripts/abraham/index.js

@@ -1,8 +1,28 @@
-//= require jquery
 //= require js-cookie/src/js.cookie
 //= require shepherd.js/dist/js/shepherd
 
-$(document).on('turbolinks:before-cache', function() {
-    // Remove visible product tours
-    $(".shepherd-step").remove();
+var Abraham = new Object();
+
+Abraham.tours = {};
+Abraham.incompleteTours = [];
+Abraham.startTour = function(tourName) {
+  if (!Shepherd.activeTour) {
+  	Abraham.tours[tourName].start();
+  }
+};
+Abraham.startNextIncompleteTour = function() {
+  if (Abraham.incompleteTours.length) {
+  	Abraham.tours[Abraham.incompleteTours[0]].checkAndStart();
+  }
+};
+
+document.addEventListener("DOMContentLoaded", Abraham.startNextIncompleteTour);
+document.addEventListener("turbolinks:load", Abraham.startNextIncompleteTour);
+
+document.addEventListener('turbolinks:before-cache', function() {
+  // Remove visible product tours
+  document.querySelectorAll(".shepherd-element").forEach(function(el) { el.remove() });
+  // Clear Abraham data
+  Abraham.tours = {};
+  Abraham.incompleteTours = [];
 });

data/app/controllers/abraham_histories_controller.rb

@@ -15,7 +15,6 @@ class AbrahamHistoriesController < ApplicationController
 
   private
 
-    # Never trust parameters from the scary internet, only allow the white list through.
     def abraham_history_params
       params.require(:abraham_history).permit(:controller_name, :action_name, :tour_name)
     end

data/app/helpers/abraham_helper.rb

@@ -3,29 +3,37 @@
 module AbrahamHelper
   def abraham_tour
     # Do we have tours for this controller/action in the user's locale?
-    tours = Rails.configuration.abraham.tours["#{controller_name}.#{action_name}.#{I18n.locale}"]
-
-    tours ||= Rails.configuration.abraham.tours["#{controller_name}.#{action_name}.#{I18n.default_locale}"]
+    tours = Rails.configuration.abraham.tours["#{controller_path}.#{action_name}.#{I18n.locale}"]
+    # Otherwise, default to the default locale
+    tours ||= Rails.configuration.abraham.tours["#{controller_path}.#{action_name}.#{I18n.default_locale}"]
 
     if tours
+      # Have any automatic tours been completed already?
       completed = AbrahamHistory.where(
         creator_id: current_user.id,
-        controller_name: controller_name,
+        controller_name: controller_path,
         action_name: action_name
       )
-      remaining = tours.keys - completed.map(&:tour_name)
 
-      if remaining.any?
-        # Generate the javascript snippet for the next remaining tour
-        render(partial: "application/abraham",
-               locals: { tour_name: remaining.first,
-                         steps: tours[remaining.first]["steps"] })
+      tour_keys_completed = completed.map(&:tour_name)
+      tour_keys = tours.keys
+
+      tour_html = ''
+
+      tour_keys.each do |key|
+        tour_html += render(partial: "application/abraham",
+               locals: { tour_name: key,
+                         tour_completed: tour_keys_completed.include?(key),
+                         trigger: tours[key]["trigger"],
+                         steps: tours[key]["steps"] })
       end
+
+      tour_html.html_safe
     end
   end
 
   def abraham_cookie_prefix
-    "abraham-#{fetch_application_name.to_s.underscore}-#{current_user.id}-#{controller_name}-#{action_name}"
+    "abraham-#{fetch_application_name.to_s.underscore}-#{current_user.id}-#{controller_path}-#{action_name}"
   end
 
   def fetch_application_name
@@ -36,7 +44,6 @@ module AbrahamHelper
     end
   end
 
-
   def abraham_domain
     request.host
   end

data/app/views/application/_abraham.html.erb

@@ -1,70 +1,81 @@
 <script>
-  var tour = new Shepherd.Tour(<%= Rails.configuration.abraham.tour_options.html_safe unless Rails.configuration.abraham.tour_options.nil? %>);
+  Abraham.tours["<%= tour_name %>"] = new Shepherd.Tour(<%= Rails.configuration.abraham.tour_options.html_safe unless Rails.configuration.abraham.tour_options.nil? %>);
 
-  tour.on("complete", function() {
-    // ajax
-    return $.ajax({
-      url: "/abraham_histories/",
-      type: "POST",
-      dataType: "json",
-      contentType: "application/json",
-      data: JSON.stringify({
+  <% if trigger != 'manual' %>
+  Abraham.tours["<%= tour_name %>"].on("complete", function() {
+    // Make AJAX call to save history of tour completion
+    return fetch("/abraham_histories/", {
+      method: "POST",
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
         authenticity_token: '<%= form_authenticity_token %>',
-        controller_name: '<%= controller_name %>',
+        controller_name: '<%= controller_path %>',
         action_name: '<%= action_name %>',
         tour_name: '<%= tour_name %>'
       })
     });
   });
 
-  tour.on("cancel", function() {
+  Abraham.tours["<%= tour_name %>"].on("cancel", function() {
     Cookies.set('<%= abraham_cookie_prefix %>-<%= tour_name %>', 'later', { domain: '<%= abraham_domain %>' });
   });
+  <% end %>
 
   <% steps.each_with_index do |(key, step), index| %>
-  tour.addStep({
+  Abraham.tours["<%= tour_name %>"].addStep({
     id: 'step-<%= key %>',
     <% if step.key?('title') %>
     title: "<%= step['title'] %>",
     <% end %>
     text: "<%= step['text'] %>",
     <% if step.key?('attachTo') %>
-    attachTo: { element: "<%= step['attachTo']['element'] %>", on: "<%= step['attachTo']['placement'] %>" },
+    attachTo: { element: "<%= escape_javascript(step['attachTo']['element'].html_safe) %>", on: "<%= step['attachTo']['placement'] %>" },
     showOn: function() {
       // Only display this step if its selector is present
-      return document.querySelector("<%= step['attachTo']['element'] %>") ? true : false
+      return document.querySelector("<%= escape_javascript(step['attachTo']['element'].html_safe) %>") ? true : false
     },
     <% end %>
     buttons: [
-    <% if index == 0 %>
-      { text: '<%= t('abraham.later') %>', action: tour.cancel, classes: 'shepherd-button-secondary' },
-      { text: '<%= t('abraham.continue') %>', action: tour.next }
+    <% if step.key?('buttons') %>
+      <% step['buttons'].each do |button| %>
+        { text: '<%= button[1]['text']  %>', action: Abraham.tours["<%= tour_name %>"].<%= button[1]['action'] %>, classes: '<%= button[1]['classes'] %>' },
+      <% end %>
     <% else %>
-        <% if index == steps.size - 1 %>
-      { text: '<%= t('abraham.done') %>', action: tour.complete }
+      <% if index == steps.size - 1 %>
+        { text: '<%= t('abraham.done') %>', action: Abraham.tours["<%= tour_name %>"].complete }
+      <% else %>
+        <% if index == 0 %>
+          { text: '<%= t('abraham.later') %>', action: Abraham.tours["<%= tour_name %>"].cancel, classes: 'shepherd-button-secondary' },
+          { text: '<%= t('abraham.continue') %>', action: Abraham.tours["<%= tour_name %>"].next }
         <% else %>
-      { text: '<%= t('abraham.exit') %>', action: tour.cancel, classes: 'shepherd-button-secondary' },
-      { text: '<%= t('abraham.next') %>', action: tour.next }
+        { text: '<%= t('abraham.exit') %>', action: Abraham.tours["<%= tour_name %>"].cancel, classes: 'shepherd-button-secondary' },
+        { text: '<%= t('abraham.next') %>', action: Abraham.tours["<%= tour_name %>"].next }
         <% end %>
+      <% end %>
     <% end %>
     ]
   });
   <% end %>
 
-  tour.start = function (start) {
-    return function () {
-      // Don't start the tour if the user dismissed it once this session
-      var tourMayStart = !Cookies.get('<%= abraham_cookie_prefix %>-<%= tour_name %>', {domain: '<%= abraham_domain %>'});
-      <% if steps.first[1]['attachTo'] %>
-      // Don't start the tour if the first step's element is missing
-      tourMayStart = tourMayStart && document.querySelector("<%= steps.first[1]['attachTo']['element'] %>");
-      <% end %>
-      
-      if (tourMayStart) {
-        start();
+  <% if trigger != "manual" %>
+    Abraham.tours["<%= tour_name %>"].checkAndStart = function (start) {
+      return function () {
+        // Don't start the tour if the user dismissed it once this session
+        var tourMayStart = !Cookies.get('<%= abraham_cookie_prefix %>-<%= tour_name %>', {domain: '<%= abraham_domain %>'});
+        <% if steps.first[1]['attachTo'] %>
+        // Don't start the tour if the first step's element is missing
+        tourMayStart = tourMayStart && document.querySelector("<%= steps.first[1]['attachTo']['element'] %>");
+        <% end %>
+        
+        if (tourMayStart) {
+          start();
+        }
       }
-    }
-  }(tour.start)
+    }(Abraham.tours["<%= tour_name %>"].start)
+
+    <% if !tour_completed %>
+    Abraham.incompleteTours.push("<%= tour_name %>");
+    <% end %>
+  <% end %>
 
-  tour.start()
 </script>

data/lib/abraham/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Abraham
-  VERSION = "2.1.2"
+  VERSION = "2.5.0"
 end

data/lib/generators/abraham/install_generator.rb

@@ -10,6 +10,7 @@ module Abraham
 
       class_option :'skip-migration', type: :boolean, desc: "Don't generate a migration for the histories table"
       class_option :'skip-initializer', type: :boolean, desc: "Don't generate an initializer"
+      class_option :'skip-config', type: :boolean, desc: "Don't generate a config file"
 
       source_root File.expand_path(File.join(File.dirname(__FILE__), "templates"))
 
@@ -24,6 +25,11 @@ module Abraham
         return if options["skip-initializer"]
 
         copy_file "initializer.rb", "config/initializers/abraham.rb"
+      end
+
+      def create_config
+        return if options["skip-config"]
+
         copy_file "abraham.yml", "config/abraham.yml"
       end
     end

data/lib/generators/abraham/templates/initializer.rb

@@ -2,18 +2,18 @@
 
 Rails.application.configure do
   tours = {}
+  tours_root = Pathname.new(Rails.root.join("config/tours"))
 
-  if Rails.root.join('config/tours').exist?
-    Dir[Rails.root.join('config/tours/*/')].each do |dir|
-      Dir[dir + '*.yml'].each do |yml|
-        path_parts = yml.split(File::SEPARATOR)
-        controller = path_parts[path_parts.size - 2]
-        file_parts = path_parts[path_parts.size - 1].split('.')
-        action = file_parts[0]
-        locale = file_parts[1]
-        t = YAML.load_file(yml)
-        tours["#{controller}.#{action}.#{locale}"] = t
-      end
+  if Rails.root.join("config/tours").exist?
+    Dir.glob(Rails.root.join("config/tours/**/*.yml")).each do |yml|
+      relative_filename = Pathname.new(yml).relative_path_from(tours_root)
+      # `controller_path` is either "controller_name" or "module_name/controller_name"
+      controller_path, filename = relative_filename.split
+      file_parts = filename.to_s.split(".")
+      action = file_parts[0]
+      locale = file_parts[1]
+      t = YAML.load_file(yml)
+      tours["#{controller_path}.#{action}.#{locale}"] = t
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abraham
 version: !ruby/object:Gem::Version
-  version: 2.1.2
+  version: 2.5.0
 platform: ruby
 authors:
 - Jonathan Abbett
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-10-22 00:00:00.000000000 Z
+date: 2022-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sassc-rails
@@ -115,7 +115,7 @@ homepage: https://github.com/actmd/abraham
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -130,9 +130,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
-signing_key: 
+rubygems_version: 3.0.8
+signing_key:
 specification_version: 4
 summary: Trackable application tours for Rails with i18n support, based on Shepherd.js.
 test_files: []