Don't start a tour if the first step's attachTo isn't present

Resolves #28, includes documentation note about step-skipping behavior.

README.md

@@ -122,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.

abraham.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'sqlite3'
   s.add_development_dependency 'rubocop'
   s.add_development_dependency 'listen'
+  s.add_development_dependency 'web-console'
 end

app/views/application/_abraham.html.erb

@@ -54,7 +54,13 @@
   tour.start = function (start) {
     return function () {
       // Don't start the tour if the user dismissed it once this session
-      if (!Cookies.get('<%= abraham_cookie_prefix %>-<%= tour_name %>', {domain: '<%= abraham_domain %>'})) {
+      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();
       }
     }

test/dummy/app/controllers/dashboard_controller.rb

@@ -2,6 +2,6 @@
 
 class DashboardController < ApplicationController
   def home; end
-
   def other; end
+  def missing; end
 end

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

@@ -0,0 +1,5 @@
+<h1>missing</h1>
+
+This page does not have the first step attachTo element,
+so we would expect the tour not to start,
+even though the second step could be rendered.

test/dummy/config/routes.rb

@@ -2,8 +2,8 @@
 
 Rails.application.routes.draw do
   get "dashboard/home"
-
   get "dashboard/other"
+  get "dashboard/missing"
 
   # For details on the DSL available within this file, see http://guides.rubyonrails.org/routing.html
 end

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

@@ -0,0 +1,10 @@
+tour:
+  steps:
+    1:
+      title: "This step points to a missing element"
+      text: "This should not skip to the second step"
+      attachTo:
+        element: "#i-dont-exist"
+        placement: "right"
+    2:
+      text: "You should not see me!"

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

@@ -3,6 +3,9 @@ tour_one:
     1:
       title: "TOUR ONE step one ENGLISH"
       text: "we show this on your first visit"
+      attachTo:
+        element: "p"
+        placement: "top"
 
 tour_two:
   steps:

test/dummy/test/system/tours_test.rb

@@ -71,4 +71,10 @@ class ToursTest < ApplicationSystemTestCase
     find("a").click
     assert_selector ".shepherd-element", visible: true
   end
+
+  test "tour with missing first step attachTo does not appear" do
+    visit dashboard_missing_url
+    # No tour should be visible, since the first step is invalid
+    refute_selector ".shepherd-element"
+  end
 end