JavaScript Initialization Code

The dynamic action attribute JavaScript Initialization Code is used by the plug-in when a dynamic action implements the plug-in action Add Step and Initialize Tour (Dynamic Action). The attribute is used to override a tour and step settings at run time of the dynamic action. It allows overriding tour and step settings using an anonymous JavaScript function. Additionally it can be used to implement Shepherd tour and step functionalities not exposed through the plug-in attributes.

The default value for an attribute is an anonymous JavaScript function accepting only one parameter pOptions. As the result, the function has to return options that will be used to create a tour and step.

function( pOptions ) {
  return pOptions;
}

The argument pOptions differs depending on the plug-in action. For Add Step, it contains all options to be applied for a new step, while for Initialize Tour (Dynamic Action) it contains all options to be applied to a new tour.

Learn more about Tour and Step options in the Shepherd documentation.

Tour Options

Tour options that are not exposed using the plug-in dynamic action attributes can be overridden using the following anonymous JavaScript function:

function( pOptions ) {

  //If true, will issue a window.confirm before cancelling
  pOptions.confirmCancel = false;

  //The message to display in the confirm dialog
  pOptions.confirmCancelMessage = "The message";

  //The prefix to add to the shepherd-enabled and shepherd-target class names as well as the data-shepherd-step-id.
  pOptions.classPrefix = "someClassName";

  //Default options for Steps (Step#constructor), created through addStep
  //the plug-in computes defaultStepOptions
  pOptions.defaultStepOptions = {};

  //Exiting the tour with the escape key will be enabled unless this is explicitly set to false.
  pOptions.exitOnEsc = true;

  //Navigating the tour via left and right arrow keys will be enabled unless this is explicitly set to false.
  pOptions.keyboardNavigation = true;

  //An optional container element for the steps. If not set, the steps will be appended to document.body
  pOptions.stepsContainer = document.body;

  //An optional container element for the modal. If not set, the modal will be appended to document.body
  pOptions.modalContainer = document.body;

  //An array of step options objects or Step instances to initialize the tour with
  //tour steps are added based on defined dynamic action, or table data
  //when this function is evaluated, none of steps are yet available
  pOptions.steps;

  return pOptions;
}

Step Options

Step options that are not exposed using the plug-in dynamic action attributes can be overridden using the following anonymous JavaScript function:

function( pOptions ) {

  //Whether to display the arrow for the tooltip or not. Defaults to true.
  pOptions.arrow = true;

  //A string of extra classes to add to the step's content element.
  pOptions.classes = "someClassName";

  //An extra class to apply to the attachTo element when it is highlighted (that is, when its step is active). You can then target that selector in your CSS.
  pOptions.highlightClass = "someClassName";

  //An array of buttons to add to the step. These will be rendered in a footer below the main body text.
  //buttons contains buttons set using the plug-in attribute Step Settings
  pOptions.buttons;

  //Extra options to pass to Popper
  pOptions.popperOptions;

  //A function that lets you override the default scrollTo behavior and define a custom action to do the scrolling, and possibly other logic.
  pOptions.scrollToHandler;

  //You can define show, hide, etc events inside when. For example:
  pOptions.when = {
    "show": function(){
      //do something when the plug-in 
    }
  }

  //A function that, when it returns true, will show the step. If it returns false, the step will be skipped.
  pOptions.showOn = function(){
    return true; 
  };

  //An action on the page which should advance shepherd to the next step. 
  //It should be an object with a string selector and an event name
  pOptions.advanceOn = {
    "selector": ".some .selector-path",
    "event": "click"
  };

  //A function that returns a promise. 
  //When the promise resolves, the rest of the show code for the step will execute.
  pOptions.beforeShowPromise = function(){ 
    return new Promise(function(resolve, reject){
      resolve();
    });
  };

  return pOptions;
}