Merge branch 'release/2.5.0'

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
@@ -131,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`
@@ -181,6 +184,29 @@ 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
+
 ### Testing your tours
 
 Abraham loads tour definitions once when you start your server. Restart your server to see tour changes.

app/views/application/_abraham.html.erb

@@ -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 %>
     ]

lib/abraham/version.rb

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

test/dummy/app/controllers/dashboard_controller.rb

@@ -5,4 +5,5 @@ def home; end
   def other; end
   def placement; end
   def missing; end
+  def buttons; end
 end

test/dummy/app/views/dashboard/buttons.html.erb

@@ -0,0 +1,6 @@
+<h1>Dashboard#buttons</h1>
+<p>Find me in app/views/dashboard/buttons.html.erb</p>
+
+<p>This page shows how custom buttons work</p>
+
+<%= link_to "Home Page", dashboard_home_url %>

test/dummy/config/routes.rb

@@ -5,6 +5,7 @@
   get "dashboard/other"
   get "dashboard/placement"
   get "dashboard/missing"
+  get "dashboard/buttons"
 
   namespace :foobar do
     get "dashboard/home"

test/dummy/config/tours/dashboard/buttons.en.yml

@@ -0,0 +1,13 @@
+button_tour:
+  steps:
+    1:
+      text: "ENGLISH custom buttons"
+      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'

test/dummy/config/tours/dashboard/buttons.es.yml

@@ -0,0 +1,13 @@
+button_tour:
+  steps:
+    1:
+      text: "SPANISH custom buttons"
+      buttons:
+        1:
+          text: 'Mas tarde'
+          action: 'cancel'
+          classes: 'custom-button shepherd-button-secondary'
+        2:
+          text: 'Ahora'
+          action: 'complete'
+          classes: 'custom-button'

test/dummy/config/tours/dashboard/home.en.yml

@@ -1,24 +1,24 @@
 intro:
   steps:
     1:
-      text: "ENGLISH This first HOME step is centered text-only"
+      text: "ENGLISH This first HOME step is centered & 'text-only'"
     2:
-      title: "ENGLISH This step has a title"
-      text: "ENGLISH This intermediate step has some text"
+      title: "ENGLISH This step has a \"title\""
+      text: 'ENGLISH This intermediate step has "some text"'
     3:
       title: "ENGLISH A missing step"
       text: "ENGLISH Refers to an element that won't exist on the page, should skip to 4"
       attachTo:
-        element: "#i-dont-exist"
+        element: "* > #i-dont-exist"
         placement: "right"
     4:
       title: "ENGLISH The final step"
       text: "ENGLISH Some text here too, and it's attached to the right"
       attachTo:
-        element: ".notice-me"
+        element: '[class="notice-me"]'
         placement: "right"
 a_manual_tour:
-  trigger: manual
+  trigger: "manual"
   steps:
     1:
       text: "You triggered the manual tour"

test/dummy/test/controllers/dashboard_controller_test.rb

@@ -36,8 +36,8 @@ class DashboardControllerTest < ActionDispatch::IntegrationTest
 
     assert_select "body script" do |element|
       # it's the home tour
-      assert element.text.include? "ENGLISH This first HOME step is centered text-only"
-      # it has three steps
+      assert element.text.include? "ENGLISH This first HOME step is centered &amp; &#39;text-only&#39;"
+      # it has four steps
       assert element.text.include? "step-1"
       assert element.text.include? "step-2"
       assert element.text.include? "step-3"
@@ -62,6 +62,23 @@ class DashboardControllerTest < ActionDispatch::IntegrationTest
     end
   end
 
+  test "should show custom buttons for locale" do
+    get dashboard_buttons_url
+    assert_response :success
+    assert_select 'body script' do |element|
+      assert element.text.include? 'Show this to me later'
+      assert element.text.include? 'Finish now'
+    end
+
+    I18n.locale = :es
+    get dashboard_buttons_url
+    assert_response :success
+    assert_select 'body script' do |element|
+      assert element.text.include? 'Mas tarde'
+      assert element.text.include? 'Ahora'
+    end
+  end
+
   test "other should have other tour code" do
     get dashboard_other_url
     assert_response :success

test/dummy/test/system/tours_test.rb

@@ -12,7 +12,7 @@ class ToursTest < ApplicationSystemTestCase
 
     # Tour Step 1
     assert_selector ".shepherd-element", visible: true
-    assert_selector ".shepherd-text", text: "ENGLISH This first HOME step is centered text-only"
+    assert_selector ".shepherd-text", text: "ENGLISH This first HOME step is centered & 'text-only'"
     assert_selector ".shepherd-button", text: "Later"
     assert_selector ".shepherd-button", text: "Continue"
     find(".shepherd-button", text: "Continue").click
@@ -23,8 +23,8 @@ class ToursTest < ApplicationSystemTestCase
     assert_selector ".shepherd-element", count: 1, visible: true
 
     # Tour Step 2
-    assert_selector ".shepherd-header", text: "ENGLISH This step has a title"
-    assert_selector ".shepherd-text", text: "ENGLISH This intermediate step has some text"
+    assert_selector ".shepherd-header", text: "ENGLISH This step has a \"title\""
+    assert_selector ".shepherd-text", text: "ENGLISH This intermediate step has \"some text\""
     assert_selector ".shepherd-button", text: "Exit"
     assert_selector ".shepherd-button", text: "Next"
     find(".shepherd-button", text: "Next").click
@@ -111,4 +111,30 @@ class ToursTest < ApplicationSystemTestCase
     visit dashboard_other_url
     refute_selector ".shepherd-element"
   end
+
+  test "tour with custom buttons" do
+    visit dashboard_buttons_url
+    assert_selector ".shepherd-element", visible: true
+    assert_selector ".shepherd-button", text: "Show this to me later"
+    assert_selector ".shepherd-button", text: "Finish now"
+
+    # Confirm that the custom buttons' specified actions work
+
+    ### Click cancel
+    find(".shepherd-button", text: "Show this to me later").click
+    ### Revisit
+    visit dashboard_buttons_url
+    ### Tour doesn't appear
+    refute_selector ".shepherd-element"
+    ### Clear the cookie
+    execute_script("Cookies.remove('abraham-dummy-#{@user_id}-dashboard-buttons-button_tour', { domain: '127.0.0.1' });")
+    ### Revisit
+    visit dashboard_buttons_url
+    ### Tour should reappear and let us click the other button
+    find(".shepherd-button", text: "Finish now").click
+    ### Revisit
+    visit dashboard_buttons_url
+    ### Tour doesn't appear (now because it's completed)
+    refute_selector ".shepherd-element"
+  end
 end