Add tests and docs for showOn

index.md

@@ -183,6 +183,7 @@ the tour, it can be any event fired on any element on the page.  You can also al
 - `renderLocation`: An `HTMLElement` or selector string of the element you want the tour step to render in. Most of the time, you will
 not need to pass anything, and it will default to `document.body`, but this is needed for `<dialog>` and might as well support passing anything.
 - `showCancelLink`: Should a cancel "✕" be shown in the header of the step?
+- `showOn`: A function that, when it returns true, will show the step. If it returns false, the step will be skipped.
 - `scrollTo`: Should the element be scrolled to when this step is shown?
 - `scrollToHandler`: A function that lets you override the default `scrollTo` behavior and define a custom action to do the scrolling,
 and possibly other logic.

src/js/tour.js

@@ -185,24 +185,24 @@ export class Tour extends Evented {
   show(key = 0, forward = true) {
     this._setupActiveTour();
 
-    const next = _.isString(key) ? this.getById(key) : this.steps[key];
+    const step = _.isString(key) ? this.getById(key) : this.steps[key];
 
-    if (!next) {
+    if (!step) {
       return;
     }
 
-    if (!_.isUndefined(next.options.showOn) && !next.options.showOn()) {
-      const index = this.steps.indexOf(next);
-      const nextIndex = forward ? index + 1 : index - 1;
-      this.show(nextIndex, forward);
+    const shouldSkipStep = _.isFunction(step.options.showOn) && !step.options.showOn();
+    // If `showOn` returns false, we want to skip the step, otherwise, show the step like normal
+    if (shouldSkipStep) {
+      this._skipStep(step, forward);
     } else {
       this.trigger('show', {
-        step: next,
+        step,
         previous: this.currentStep
       });
 
-      this.currentStep = next;
-      next.show();
+      this.currentStep = step;
+      step.show();
     }
   }
 
@@ -231,6 +231,18 @@ export class Tour extends Evented {
 
     Shepherd.activeTour = this;
   }
+
+  /**
+   * Called when `showOn` evaluates to false, to skip the step
+   * @param {Step} step The step to skip
+   * @param {Boolean} forward True if we are going forward, false if backward
+   * @private
+   */
+  _skipStep(step, forward) {
+    const index = this.steps.indexOf(step);
+    const nextIndex = forward ? index + 1 : index - 1;
+    this.show(nextIndex, forward);
+  }
 }
 
 export { Shepherd };

test/test.tour.js

@@ -6,13 +6,14 @@ import { Step } from '../src/js/step';
 window.Shepherd = Shepherd;
 
 describe('Tour', function() {
-  let instance;
+  let instance, shouldShowStep;
   const defaults = {
     classes: 'shepherd-theme-arrows',
     scrollTo: true
   };
 
   beforeEach(() => {
+    shouldShowStep = false;
     instance = new Shepherd.Tour({
       defaults
     });
@@ -23,6 +24,15 @@ describe('Tour', function() {
       title: 'This is a test step for our tour'
     });
 
+    instance.addStep('skipped-step', {
+      classes: 'skipped',
+      id: 'skipped-step',
+      title: 'This step should be skipped',
+      showOn() {
+        return shouldShowStep;
+      }
+    });
+
     instance.addStep('test2', {
       id: 'test2',
       title: 'Another Step'
@@ -61,7 +71,7 @@ describe('Tour', function() {
 
   describe('.addStep()', function() {
     it('adds tour steps', function() {
-      assert.equal(instance.steps.length, 3);
+      assert.equal(instance.steps.length, 4);
       assert.equal(instance.getById('test').options.classes, 'foo', 'classes passed to step options');
     });
 
@@ -70,7 +80,7 @@ describe('Tour', function() {
         id: 'one-arg'
       });
 
-      assert.equal(instance.steps.length, 4);
+      assert.equal(instance.steps.length, 5);
       assert.equal(step.id, 'one-arg', 'id applied to step with just one arg');
     });
 
@@ -79,15 +89,15 @@ describe('Tour', function() {
         id: 'already-a-step'
       }));
 
-      assert.equal(instance.steps.length, 4);
+      assert.equal(instance.steps.length, 5);
       assert.equal(step.id, 'already-a-step', 'id applied to step instance');
       assert.equal(step.tour, instance, 'tour is set to `this`');
     });
   });
 
   describe('.getById()', function() {
     it('returns the step by ID with the right title', function() {
-      assert.equal(instance.steps.length, 3);
+      assert.equal(instance.steps.length, 4);
       assert.equal(instance.getById('test3').options.title, 'Yet, another test step');
     });
 
@@ -159,21 +169,21 @@ describe('Tour', function() {
   describe('.removeStep()', function() {
     it('removes the step when passed the id', function() {
       instance.start();
-      assert.equal(instance.steps.length, 3);
+      assert.equal(instance.steps.length, 4);
       instance.removeStep('test2');
-      assert.equal(instance.steps.length, 2);
+      assert.equal(instance.steps.length, 3);
     });
 
     it('hides the step before removing', function() {
       let hideFired = false;
       instance.start();
-      assert.equal(instance.steps.length, 3);
+      assert.equal(instance.steps.length, 4);
       const step = instance.getById('test');
       step.on('hide', () => {
         hideFired = true;
       });
       instance.removeStep('test');
-      assert.equal(instance.steps.length, 2);
+      assert.equal(instance.steps.length, 3);
       assert.isOk(hideFired, 'hide is fired before step is destroyed');
     });
   });
@@ -188,5 +198,17 @@ describe('Tour', function() {
       instance.show('not-a-real-key');
       assert.isNotOk(showFired, 'showFired is false because show short circuits');
     });
+
+    it('showOn determines which steps to skip', function() {
+      instance.start();
+      assert.equal(instance.getCurrentStep().id, 'test');
+      instance.next();
+      assert.equal(instance.getCurrentStep().id, 'test2');
+      assert.notEqual(instance.getCurrentStep().id, 'skipped-step', 'step skipped because `showOn` returns false');
+      instance.back();
+      shouldShowStep = true;
+      instance.next();
+      assert.equal(instance.getCurrentStep().id, 'skipped-step', 'step shown because `showOn` returns true');
+    });
   });
 });