abraham 1.5.3 → 2.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5e2441be140ebda54d2e6d25d2bab0f9ff1c4a60c074ad47f05e56675f70ec6
-  data.tar.gz: 5389309e36ef642778c020ec0674143ea96875c7694b96ecc7fe5644cf87ceaf
+  metadata.gz: 934942f3a067c17e06029f1095f7abf5b570d5e7b63a8d16601769df4d3300e1
+  data.tar.gz: 2389400109634350208fff528edf7c70577982677f34e8af9ef84dcb49aa9d5a
 SHA512:
-  metadata.gz: fb21305418c187e1f72eededaa0a4a40a3d7af01cf819b18a34d96f0015c322a70f4ac1cb227ac0d8107e30093695d0a2f21af6d0f01a0d9457b75853fc79b32
-  data.tar.gz: 6dff4bceecb90c0ef59246a8442fa605498fd4c6870df9e4ae68cff5b8b70b585e2604607086ca40323b3adba5bf26d66945a234e2845b223f64b697b2aeb30d
+  metadata.gz: ec5c02fcd3b19038b65b9a3af6ce3d84f585c47e465a914021d05a18c340665fb1891fb590fb76b332a05eb5d7e6736e89aba9e854cf94ad0acb921c4cc623ce
+  data.tar.gz: c00a73dfe7269459459fadaa4db889de665ec0601273fa431d94372cf38383e4f0a5c1b5959fbf0a7f5ea681fb149948dadc2ec4670e09941b54356979500274

data/README.md

@@ -6,11 +6,12 @@ _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.js](http://github.hubspot.com/shepherd/docs/welcome/) 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 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.
 
 * 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
 
 ## Requirements
 
@@ -36,7 +37,7 @@ $ rails db:migrate
 Install the JavaScript dependencies:
 
 ```
-$ yarn add jquery js-cookie shepherd.js
+$ yarn add jquery@^3.4.0 js-cookie@^2.2.0 shepherd.js@^6.0.0-beta
 ```
 
 Require `abraham` in `app/assets/javascripts/application.js`
@@ -45,29 +46,26 @@ Require `abraham` in `app/assets/javascripts/application.js`
 //= require abraham
 ```
 
-Require a Shepherd.js CSS theme in `app/assets/stylesheets/application.scss`
+Require a CSS theme in `app/assets/stylesheets/application.scss`
 
 ```
-//= require "shepherd.js/dist/css/shepherd-theme-default"
+*= require abraham/theme-default
 ```
 
-Shepherd.js provides the following themes:
+Abraham provides the following themes:
 
-- `shepherd-theme-arrows`
-- `shepherd-theme-arrows-fix`
-- `shepherd-theme-arrows-plain-buttons`
-- `shepherd-theme-dark`
-- `shepherd-theme-default`
-- `shepherd-theme-square`
-- `shepherd-theme-square-dark`
+- `theme-default`
+- `theme-dark`
 
 Update `config/abraham.yml` if you choose a different theme:
 
 ```
 defaults: &defaults
-  :default_theme: 'shepherd-theme-arrows'
+  :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
@@ -124,6 +122,11 @@ Abraham takes care of which buttons should appear with each step:
 * "Exit" and "Next" buttons on intermediate steps
 * "Done" button on the last step
 
+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.
@@ -136,6 +139,24 @@ 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.
+
+If you were using Abraham v1, you'll want to take the following steps to upgrade:
+
+1. Update your gem to the latest version
+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`. 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!
+
 ## Contributing
 
 Contributions are welcome!
@@ -150,6 +171,8 @@ Everyone interacting in Abraham's codebase, issue tracker, etc. is expected to f
 
 This Rails engine contains a test app called `dummy` with controller and system tests. They'll all get run with `rails t`.
 
+Please 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.
+
 Final testing should be done in a standalone Rails app, following the README instructions.
 
 To install the `abraham` gem with a local path:
@@ -160,7 +183,7 @@ gem 'abraham', path: '~/Workspace/abraham'
 
 #### Automated testing
 
-We use TravisCI automatically testing this rails engine. For test history, venture over to [TravisCI](https://travis-ci.com/actmd/abraham).
+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).
 
 ### Releasing
 

data/app/assets/stylesheets/abraham/_common.scss

@@ -0,0 +1,194 @@
+.shepherd-button {
+  background: #3288e6;
+  border: 0;
+  border-radius: 3px;
+  color: hsla(0, 0%, 100%, .75);
+  cursor: pointer;
+  margin-right: .5rem;
+  padding: .5rem 1.5rem;
+  transition: all .5s ease;
+}
+
+.shepherd-button:not(:disabled):hover {
+  background: #196fcc;
+  color: hsla(0, 0%, 100%, .75);
+}
+
+.shepherd-button.shepherd-button-secondary {
+  background: #f1f2f3;
+  color: rgba(0, 0, 0, .75);
+}
+
+.shepherd-button.shepherd-button-secondary:not(:disabled):hover {
+  background: #d6d9db;
+  color: rgba(0, 0, 0, .75);
+}
+
+.shepherd-button:disabled {
+  cursor: not-allowed;
+}
+
+.shepherd-footer {
+  border-bottom-left-radius: 5px;
+  border-bottom-right-radius: 5px;
+  display: flex;
+  justify-content: flex-end;
+  padding: 0 1rem 1rem;
+}
+
+.shepherd-footer .shepherd-button:last-child {
+  margin-right: 0;
+}
+
+.shepherd-cancel-icon {
+  background: transparent;
+  border: none;
+  color: hsla(0, 0%, 50.2%, .75);
+  font-size: 2em;
+  cursor: pointer;
+  font-weight: 400;
+  margin: 0;
+  padding: 0;
+  transition: color .5s ease;
+}
+
+.shepherd-cancel-icon:hover {
+  color: rgba(0, 0, 0, .75);
+}
+
+.shepherd-has-title .shepherd-content .shepherd-cancel-icon {
+  color: hsla(0, 0%, 50.2%, .75);
+}
+
+.shepherd-has-title .shepherd-content .shepherd-cancel-icon:hover {
+  color: rgba(0, 0, 0, .75);
+}
+
+.shepherd-title {
+  display: flex;
+  font-size: 1rem;
+  font-weight: 400;
+  flex: 1 0 auto;
+  margin: 0;
+  padding: 0;
+}
+
+.shepherd-header {
+  align-items: center;
+  border-top-left-radius: 5px;
+  border-top-right-radius: 5px;
+  display: flex;
+  justify-content: flex-end;
+  padding: 0.5rem 1rem 0;
+}
+
+.shepherd-has-title .shepherd-content .shepherd-header {
+  padding: 1rem;
+}
+
+.shepherd-text {
+  font-size: 1rem;
+  padding: 1rem;
+}
+
+.shepherd-text p {
+  margin-top: 0;
+}
+
+.shepherd-text p:last-child {
+  margin-bottom: 0;
+}
+
+.shepherd-content {
+  border-radius: 5px;
+  outline: none;
+  padding: 0;
+}
+
+.shepherd-element {
+  border-radius: 5px;
+  box-shadow: 0 1px 4px rgba(0, 0, 0, .2);
+  max-width: 400px;
+  outline: none;
+  z-index: 9999;
+  line-height: 1.2;
+}
+
+.shepherd-element,
+.shepherd-element *,
+.shepherd-element :after,
+.shepherd-element :before {
+  box-sizing: border-box;
+}
+
+.shepherd-element .shepherd-arrow {
+  border: 16px solid transparent;
+  content: "";
+  display: block;
+  height: 16px;
+  pointer-events: none;
+  position: absolute;
+  width: 16px;
+  z-index: 10000;
+}
+
+.shepherd-element.shepherd-element-attached-bottom.shepherd-element-attached-center .shepherd-arrow,
+.shepherd-element.shepherd-pinned-top .shepherd-arrow {
+  bottom: 0;
+  border-top-color: #232323;
+  left: 50%;
+  transform: translate(-50%, 100%);
+}
+
+.shepherd-element.shepherd-element-attached-top.shepherd-element-attached-center .shepherd-arrow {
+  border-bottom-color: #232323;
+  left: 50%;
+  top: 0;
+  transform: translate(-50%, -100%);
+}
+
+.shepherd-element.shepherd-element-attached-top.shepherd-element-attached-center.shepherd-has-title .shepherd-arrow {
+  border-bottom-color: #303030;
+}
+
+.shepherd-element.shepherd-element-attached-middle.shepherd-element-attached-left .shepherd-arrow,
+.shepherd-element.shepherd-pinned-right .shepherd-arrow {
+  border-right-color: #232323;
+  left: 0;
+  top: 50%;
+  transform: translate(-100%, -50%);
+}
+
+.shepherd-element.shepherd-element-attached-middle.shepherd-element-attached-right .shepherd-arrow,
+.shepherd-element.shepherd-pinned-left .shepherd-arrow {
+  border-left-color: #232323;
+  right: 0;
+  top: 50%;
+  transform: translate(100%, -50%);
+}
+
+.shepherd-modal-overlay-container {
+  -ms-filter: progid:dximagetransform.microsoft.gradient.alpha(Opacity=50);
+  filter: alpha(opacity=50);
+  fill-rule: evenodd;
+  height: 0;
+  left: 0;
+  opacity: 0;
+  overflow: hidden;
+  pointer-events: none;
+  position: fixed;
+  top: 0;
+  transition: all .3s ease-out, height 0ms .3s, opacity .3s 0ms;
+  width: 100vw;
+  z-index: 9997;
+}
+
+.shepherd-modal-overlay-container.shepherd-modal-is-visible {
+  height: 100vh;
+  opacity: .5;
+  transition: all .3s ease-out, height 0s 0s, opacity .3s 0s;
+}
+
+.shepherd-modal-overlay-container.shepherd-modal-is-visible path {
+  pointer-events: all;
+}

data/app/assets/stylesheets/abraham/theme-dark.scss

@@ -0,0 +1,40 @@
+@import "_common";
+
+.theme-dark.shepherd-element {
+  background: #232323;
+
+  .shepherd-text {
+    color: #eee;
+  }
+
+  .shepherd-title {
+    color: #fff;
+  }
+
+  &.shepherd-has-title .shepherd-content .shepherd-header {
+    background: #303030;
+  }
+
+  &.shepherd-element-attached-bottom.shepherd-element-attached-center .shepherd-arrow,
+  &.shepherd-pinned-top .shepherd-arrow {
+    border-top-color: #232323;
+  }
+
+  &.shepherd-element-attached-top.shepherd-element-attached-center .shepherd-arrow {
+    border-bottom-color: #232323;
+  }
+
+  &.shepherd-element-attached-top.shepherd-element-attached-center.shepherd-has-title .shepherd-arrow {
+    border-bottom-color: #303030;
+  }
+
+  &.shepherd-element-attached-middle.shepherd-element-attached-left .shepherd-arrow,
+  &.shepherd-pinned-right .shepherd-arrow {
+    border-right-color: #232323;
+  }
+
+  &.shepherd-element-attached-middle.shepherd-element-attached-right .shepherd-arrow,
+  &.shepherd-pinned-left .shepherd-arrow {
+    border-left-color: #232323;
+  }
+}

data/app/assets/stylesheets/abraham/theme-default.scss

@@ -0,0 +1,40 @@
+@import "_common";
+
+.theme-default.shepherd-element {
+  background: #fff;
+
+  .shepherd-text {
+    color: rgba(0, 0, 0, .75);
+  }
+
+  .shepherd-title {
+    color: rgba(0, 0, 0, .75);
+  }
+
+  &.shepherd-has-title .shepherd-content .shepherd-header {
+    background: #e6e6e6;
+  }
+
+  &.shepherd-element-attached-bottom.shepherd-element-attached-center .shepherd-arrow,
+  &.shepherd-pinned-top .shepherd-arrow {
+    border-top-color: #fff;
+  }
+
+  &.shepherd-element-attached-top.shepherd-element-attached-center .shepherd-arrow {
+    border-bottom-color: #fff;
+  }
+
+  &.shepherd-element-attached-top.shepherd-element-attached-center.shepherd-has-title .shepherd-arrow {
+    border-bottom-color: #e6e6e6;
+  }
+
+  &.shepherd-element-attached-middle.shepherd-element-attached-left .shepherd-arrow,
+  &.shepherd-pinned-right .shepherd-arrow {
+    border-right-color: #fff;
+  }
+
+  &.shepherd-element-attached-middle.shepherd-element-attached-right .shepherd-arrow,
+  &.shepherd-pinned-left .shepherd-arrow {
+    border-left-color: #fff;
+  }
+}

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,9 +1,5 @@
 <script>
-  var tour = new Shepherd.Tour({
-    defaults: {
-      classes: '<%= Rails.configuration.abraham.default_theme %>'
-    }
-  });
+  var tour = new Shepherd.Tour(<%= Rails.configuration.abraham.tour_options.html_safe unless Rails.configuration.abraham.tour_options.nil? %>);
 
   tour.on("complete", function() {
     // ajax
@@ -26,7 +22,8 @@
   });
 
   <% steps.each_with_index do |(key, step), index| %>
-  tour.addStep('step-<%= key %>', {
+  tour.addStep({
+    id: 'step-<%= key %>',
     <% if step.key?('title') %>
     title: "<%= step['title'] %>",
     <% end %>
@@ -54,8 +51,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 = "1.5.3"
+  VERSION = "2.1.2"
 end

data/lib/generators/abraham/templates/abraham.yml

@@ -1,5 +1,8 @@
 defaults: &defaults
-  :default_theme: 'shepherd-theme-default'
+  # Add any valid Shepherd.js configuration JSON here
+  # and it will be passed into the `new Shepherd.Tour()`
+  # initializer.
+  :tour_options: '{ defaultStepOptions: { classes: "theme-default" } }'
 
 development:
   <<: *defaults

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

@@ -19,6 +19,6 @@ Rails.application.configure do
 
   abraham_config = Rails.application.config_for :abraham
   config.abraham = ActiveSupport::OrderedOptions.new
-  config.abraham.default_theme = abraham_config[:default_theme]
+  config.abraham.tour_options = abraham_config[:tour_options]
   config.abraham.tours = tours
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abraham
 version: !ruby/object:Gem::Version
-  version: 1.5.3
+  version: 2.1.2
 platform: ruby
 authors:
 - Jonathan Abbett
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-04 00:00:00.000000000 Z
+date: 2020-10-22 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
@@ -77,6 +91,9 @@ files:
 - Rakefile
 - app/assets/config/abraham_manifest.js
 - app/assets/javascripts/abraham/index.js
+- app/assets/stylesheets/abraham/_common.scss
+- app/assets/stylesheets/abraham/theme-dark.scss
+- app/assets/stylesheets/abraham/theme-default.scss
 - app/controllers/abraham_histories_controller.rb
 - app/helpers/abraham_helper.rb
 - app/models/abraham_history.rb
@@ -113,7 +130,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubyforge_project: 
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Trackable application tours for Rails with i18n support, based on Shepherd.js.