abraham 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8a61048b60ffe74990a86c146886551d315f2da86eb70ce31f5b28dcdb4fe5e
-  data.tar.gz: 8dc414098b445450cf739cec4b5b43b4b15c0322bacbc2d5dc4b2ba3f2e3aa45
+  metadata.gz: d6094c0e5929d5da7e61f12bd1e60a11e450a05e2c3b99afc349b0b7d847edca
+  data.tar.gz: 2b6df2f7d73f7b0c312b13ca3bc5adf16452437f1fd97faea90468093193f5fa
 SHA512:
-  metadata.gz: 17a96b08513bd5adda880abe973557c685b8c4b4d0aba48475ec6c1dcf5fcda2192f72a3536ab5fa01f7740353dcc38e24e9a2a8236a3e3684c17050b679f486
-  data.tar.gz: 57d9abd011c6168fabfba830288f0855a9a24e40a634254264d453efb3d2c556d7ef685b751729bcd9e69ba460cf0652415d20ab82f03244a2e85775d869eebd
+  metadata.gz: 978175580bd5132ea570ea0c14421f6ac0def8ca523ce5dfea730c3934c49180c6f9909fd35f161190afddf02aade22c9d447cb74546c419d8cd143e77129d3e
+  data.tar.gz: 9c46128409adfc46ed76abe7f07601d4e5035c63641c13e50b747e51a2e532910326ed77f63f7b2406feb4f5930feb8dbdbe10e5b660f858409f1ce7cf8f186c

data/README.md

@@ -15,7 +15,8 @@ Abraham injects dynamically-generated [Shepherd](https://shepherdjs.dev/) JavaSc
 
 ## 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.
+* Abraham is tested on Rails 5.2, 6.0, and 6.1
 
 ## Installation
 
@@ -95,7 +96,7 @@ NB: You must specify a locale in the filename, even if you're only supporting on
 
 ### 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.
+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 in a particular position (see below).
 
 ```yaml
 intro:
@@ -122,6 +123,23 @@ Abraham takes care of which buttons should appear with each step:
 * "Exit" and "Next" buttons on intermediate steps
 * "Done" button on the last step
 
+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))
+
 ### Testing your tours
 
 Abraham loads tour definitions once when you start your server. Restart your server to see tour changes.
@@ -134,6 +152,10 @@ Rails.application.configure do
 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.
+
 ## Upgrading from version 1
 
 Abraham v1 was built using Shepherd 1.8, v2 now uses Shepherd 6 -- quite a jump, yes.
@@ -144,11 +166,7 @@ If you were using Abraham v1, you'll want to take the following steps to upgrade
 1. Fix your yarn dependencies to use the right versions
 1. 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.
 1. 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`
-1. There's been a slight change to `initializers/abraham.rb`. You can just change line 22 to:
-
-```rb
-config.abraham.tour_options = abraham_config[:tour_options]
-```
+1. 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).
 
 If you have any trouble at all, please [submit an issue](https://github.com/actmd/abraham/issues) for assistance!
 
@@ -156,10 +174,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
@@ -178,7 +212,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 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).
 
 ### 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,7 @@
-//= 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();
+document.addEventListener('turbolinks:before-cache', function() {
+  // Remove visible product tours
+  document.querySelectorAll(".shepherd-element").forEach(function(el) { el.remove() });
 });

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

@@ -25,9 +25,18 @@ module AbrahamHelper
   end
 
   def abraham_cookie_prefix
-    "abraham-#{Rails.application.class.parent.to_s.underscore}-#{current_user.id}-#{controller_name}-#{action_name}"
+    "abraham-#{fetch_application_name.to_s.underscore}-#{current_user.id}-#{controller_name}-#{action_name}"
   end
 
+  def fetch_application_name
+    if Module.method_defined?(:module_parent)
+      Rails.application.class.module_parent
+    else
+      Rails.application.class.parent
+    end
+  end
+
+
   def abraham_domain
     request.host
   end

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

@@ -1,14 +1,12 @@
 <script>
-  const tour = new Shepherd.Tour(<%= Rails.configuration.abraham.tour_options.html_safe unless Rails.configuration.abraham.tour_options.nil? %>);
+  var tour = 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({
+    // 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 %>',
         action_name: '<%= action_name %>',
@@ -51,8 +49,20 @@
   });
   <% end %>
 
-  // Don't start the tour if the user dismissed it once this session
-  if (!Cookies.get('<%= abraham_cookie_prefix %>-<%= tour_name %>', { domain: '<%= abraham_domain %>' })) {
-    tour.start();
-  }
+  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();
+      }
+    }
+  }(tour.start)
+
+  tour.start()
 </script>

data/lib/abraham/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abraham
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Jonathan Abbett
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-10-17 00:00:00.000000000 Z
+date: 2021-04-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sassc-rails
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: web-console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Trackable application tours for Rails with i18n support, based on Shepherd.js.
 email:
 - jonathan@act.md
@@ -101,7 +115,7 @@ homepage: https://github.com/actmd/abraham
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -116,8 +130,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
-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: []