From 9c073cf2e0726bd5b8325fd613cf610b52fced65 Mon Sep 17 00:00:00 2001 From: Jonathan Abbett Date: Thu, 17 Oct 2019 17:59:39 -0400 Subject: [PATCH] Upgrade to Shepherd v6, resolves #22, #14, #8 --- .gitignore | 3 + Gemfile | 4 + README.md | 46 +++-- app/assets/images/abraham/.keep | 0 app/assets/stylesheets/abraham/_common.scss | 194 ++++++++++++++++++ .../stylesheets/abraham/theme-dark.scss | 40 ++++ .../stylesheets/abraham/theme-default.scss | 40 ++++ app/mailers/.keep | 0 app/views/application/_abraham.html.erb | 9 +- lib/abraham/version.rb | 2 +- lib/generators/abraham/templates/abraham.yml | 5 +- .../abraham/templates/initializer.rb | 2 +- package.json | 2 +- .../app/assets/stylesheets/application.css | 2 +- .../app/assets/stylesheets/dashboard.css | 4 - test/dummy/config/abraham.yml | 2 +- test/dummy/config/initializers/abraham.rb | 2 +- test/dummy/config/tours/dashboard/home.en.yml | 4 +- test/dummy/config/tours/dashboard/home.es.yml | 4 +- .../controllers/dashboard_controller_test.rb | 17 +- test/dummy/test/system/tours_test.rb | 22 +- yarn.lock | 74 ------- 22 files changed, 350 insertions(+), 128 deletions(-) delete mode 100644 app/assets/images/abraham/.keep create mode 100644 app/assets/stylesheets/abraham/_common.scss create mode 100755 app/assets/stylesheets/abraham/theme-dark.scss create mode 100755 app/assets/stylesheets/abraham/theme-default.scss delete mode 100644 app/mailers/.keep delete mode 100644 test/dummy/app/assets/stylesheets/dashboard.css delete mode 100644 yarn.lock diff --git a/.gitignore b/.gitignore index 3e3ef8e..dfd7a04 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,8 @@ capybara-*.html **.orig rerun.txt pickle-email-*.html +# Don't commit yarn.lock, to ensure that package.json is specific enough +yarn.lock yarn-error.log # TODO Comment out these rules if you are OK with secrets being uploaded to the repo @@ -52,3 +54,4 @@ bower.json .idea/ /test/dummy/tmp/ /test/dummy/log/ +.DS_Store \ No newline at end of file diff --git a/Gemfile b/Gemfile index b2ce468..7d3fd4b 100644 --- a/Gemfile +++ b/Gemfile @@ -1,6 +1,10 @@ # frozen_string_literal: true source 'http://rubygems.org' +group :development, :test do + gem 'sassc-rails' +end + # Set the Rails version. We have this switch so that we can test multiple # versions for Rails on Travis CI. # Inspired by http://aaronmiler.com/blog/testing-your-rails-engine-with-multiple-versions-of-rails/ diff --git a/README.md b/README.md index 4ad7a47..7591c75 100644 --- a/README.md +++ b/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 @@ -136,6 +134,24 @@ Rails.application.configure do end ``` +## 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`. You can just change line 22 to: + +```rb +config.abraham.tour_options = abraham_config[:tour_options] +``` + +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 +166,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 +178,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 diff --git a/app/assets/images/abraham/.keep b/app/assets/images/abraham/.keep deleted file mode 100644 index e69de29..0000000 diff --git a/app/assets/stylesheets/abraham/_common.scss b/app/assets/stylesheets/abraham/_common.scss new file mode 100644 index 0000000..2ebfc0a --- /dev/null +++ b/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; +} \ No newline at end of file diff --git a/app/assets/stylesheets/abraham/theme-dark.scss b/app/assets/stylesheets/abraham/theme-dark.scss new file mode 100755 index 0000000..8de47d3 --- /dev/null +++ b/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; + } +} diff --git a/app/assets/stylesheets/abraham/theme-default.scss b/app/assets/stylesheets/abraham/theme-default.scss new file mode 100755 index 0000000..68f6663 --- /dev/null +++ b/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; + } +} \ No newline at end of file diff --git a/app/mailers/.keep b/app/mailers/.keep deleted file mode 100644 index e69de29..0000000 diff --git a/app/views/application/_abraham.html.erb b/app/views/application/_abraham.html.erb index 184299a..c95bd0a 100644 --- a/app/views/application/_abraham.html.erb +++ b/app/views/application/_abraham.html.erb @@ -1,9 +1,5 @@