abraham 2.3.0.beta → 2.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5872e5ab9e3d24a4133de7b4127934eba2b36688eac51eb4f29bfdd9c7a0f1ff
-  data.tar.gz: ead10365b2cdf82e9f9e49f7ee55d9525731093b0b1b6faafe720b789766c977
+  metadata.gz: 3f58e765abccdc1ca54c84235af22089873e9d3a5de2b4e862a85273f58d56a9
+  data.tar.gz: a8e6aafc28d11ebbb4c593c010d0d5eb5a9b204897394286bd1cdc3a5b4e67ef
 SHA512:
-  metadata.gz: 810d59a5b7d8f35d787d65fec4e42c46cb27edc7228272aa337adb31ddf9a4f35167610046f99861af51ccd0a65dea2bd77d32ac41f8fd07ed5f349516faa8b4
-  data.tar.gz: bfe6c59e405805b0e98938480037fc5a2c40ef4ae965558060ac4767cbc522890b131f634a190847b92d759b9facd7ba472d4f67b8a0b32eb183f660164f7487
+  metadata.gz: 05f6395978a18eb6cdfec2acae497620fdeee810e63fc3c78a314424b5d5f613017627bbad83182e8e42bb6fb0c0fe945f12cb6e28ee56794dc180014883267e
+  data.tar.gz: cc2846b357694af6e720cdc87d081968625f76870090116d056a7d5ace468bb6077231f5fb8e061b650a4c1fed6ee6e6d14d19c9ffe999d42ec5348d3fc4c3b3

data/README.md

@@ -17,6 +17,7 @@ Abraham makes it easy to show guided tours to users of your Rails application. W
 ## 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
@@ -78,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 corresponding to the views defined in your application. Its directory structure mirrors your application's controllers, and the tour files 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/
@@ -128,6 +132,8 @@ 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`
@@ -147,7 +153,8 @@ Abraham tries to be helpful when your tour steps attach to page elements that ar
 
 ### 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:
+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:
@@ -177,6 +184,52 @@ This tour will not start automatically; instead, use the `Abraham.startTour` met
 </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
+
+### Flipper integration
+
+If 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.
+
+```yml
+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".
+
+```yml
+walkthrough:
+  flipper_key: "name_of_flipper"
+  flipper_activation: "disabled"
+  steps:
+    1:
+      text: "This walkthrough will show you how to..."
+```
+
 ### Testing your tours
 
 Abraham loads tour definitions once when you start your server. Restart your server to see tour changes.
@@ -193,7 +246,18 @@ end
 
 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
+
+### 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.
 
@@ -249,7 +313,7 @@ gem 'abraham', path: '~/Workspace/abraham'
 
 #### Automated testing
 
-We use TravisCI to automatically test this engine with Rails 5.2, 6.0, and 6.1. 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/app/helpers/abraham_helper.rb

@@ -1,17 +1,19 @@
 # frozen_string_literal: true
 
 module AbrahamHelper
+  include FlipperHelper
+
   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_path}.#{action_name}.#{I18n.locale}"]
     # Otherwise, default to the default locale
-    tours ||= Rails.configuration.abraham.tours["#{controller_name}.#{action_name}.#{I18n.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
       )
 
@@ -21,11 +23,16 @@ module AbrahamHelper
       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"] })
+        flipper_key = tours[key]["flipper_key"]
+        flipper_activation = tours[key]["flipper_activation"]
+
+        if should_add_tour(flipper_key, flipper_activation)
+          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
       end
 
       tour_html.html_safe
@@ -33,7 +40,7 @@ module AbrahamHelper
   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
@@ -44,7 +51,6 @@ module AbrahamHelper
     end
   end
 
-
   def abraham_domain
     request.host
   end

data/app/helpers/flipper_helper.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module FlipperHelper
+  def should_add_tour(flipper_key, flipper_activation)
+    return true if !flipper_defined?
+
+    case process_activation_option(flipper_activation)
+    when "enabled"
+      return (flipper_key && Flipper.enabled?(flipper_key.to_sym)) || flipper_key.nil?
+    when "disabled"
+      return (flipper_key && !Flipper.enabled?(flipper_key.to_sym)) || flipper_key.nil?
+    else
+      return false
+    end
+  end
+
+  private
+    def flipper_defined?
+      Object.const_defined?("Flipper")
+    end
+
+    def process_activation_option(flipper_activation)
+      return "disabled" if flipper_activation == "disabled"
+      "enabled"
+    end
+end

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

@@ -9,7 +9,7 @@
       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 %>'
       })
@@ -29,22 +29,28 @@
     <% 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 == steps.size - 1 %>
-      { text: '<%= t('abraham.done') %>', action: Abraham.tours["<%= tour_name %>"].complete }
+    <% 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 == 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 }
+      <% if index == steps.size - 1 %>
+        { text: '<%= t('abraham.done') %>', action: Abraham.tours["<%= tour_name %>"].complete }
       <% else %>
-      { text: '<%= t('abraham.exit') %>', action: Abraham.tours["<%= tour_name %>"].cancel, classes: 'shepherd-button-secondary' },
-      { text: '<%= t('abraham.next') %>', action: Abraham.tours["<%= tour_name %>"].next }
+        <% 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: Abraham.tours["<%= tour_name %>"].cancel, classes: 'shepherd-button-secondary' },
+        { text: '<%= t('abraham.next') %>', action: Abraham.tours["<%= tour_name %>"].next }
+        <% end %>
       <% end %>
     <% end %>
     ]

data/lib/abraham/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Abraham
-  VERSION = "2.3.0.beta"
+  VERSION = "2.5.1"
 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.3.0.beta
+  version: 2.5.1
 platform: ruby
 authors:
 - Jonathan Abbett
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-21 00:00:00.000000000 Z
+date: 2022-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sassc-rails
@@ -96,6 +96,7 @@ files:
 - app/assets/stylesheets/abraham/theme-default.scss
 - app/controllers/abraham_histories_controller.rb
 - app/helpers/abraham_helper.rb
+- app/helpers/flipper_helper.rb
 - app/models/abraham_history.rb
 - app/models/application_record.rb
 - app/views/application/_abraham.html.erb
@@ -126,9 +127,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.0.8
 signing_key: