- Rollup/Webpack Based Builds
-The latest versions of Rollup and Webpack support ES6 imports. We have an ES module
-exported to dist/js/shepherd.esm.js. This is also specified as "module" in
-package.json, which should allow you to import using standard ES import syntax.
-i.e.
-import Shepherd from 'shepherd.js';
-
-First create a new Tour instance for your tour:
-const tour = new Shepherd.Tour({
- defaultStepOptions: {
- classes: 'shadow-md bg-purple-dark',
- scrollTo: true
- }
-});
-
-The defaultStepOptions option allows you to specify any options which should be applied
-to all this tour's steps by default.
-Next, add your steps:
-tour.addStep('example-step', {
- text: 'This step is attached to the bottom of the <code>.example-css-selector</code> element.',
- attachTo: {
- element: '.example-css-selector',
- on: 'bottom'
- },
- classes: 'example-step-extra-class',
- buttons: [
- {
- text: 'Next',
- action: tour.next
- }
- ]
-});
-
-Finally, to start the tour, just call start on your Tour instance:
-tour.start();
-
-If you need to remove a step from your tour, call removeStep on your Tour instance. If the step currently being displayed is the one you're removing, and there are steps left in the tour, then the first one will be shown, otherwise, the tour will be cancelled.
-tour.removeStep('example-step');
-
-API
-Global Shepherd Object
-Shepherd exposes a single object onto the window, Shepherd.
-That global object fires several events to let you link up actions with events
-occurring in any tour:
-Methods
-
-Shepherd.on(eventName, handler, [context]): Bind an eventShepherd.off(eventName, [handler]): Unbind an eventShepherd.once(eventName, handler, [context]): Bind just the next instance of an event
-Events
-The global Shepherd fires the following events whenever a Tour instance fires them. It adds to the object passed to the
-event handlers a tour key pointing to the instance which fired the event:
-
-completecancelhideshowstartactiveinactive
-Current Tour
-The global Shepherd includes a property which is always set to the currently active tour, or null if there is no active tour:
-
-Tour Instances
-Creation
-You create a Tour object for each tour you'd like to create.
-Tour's constructor accepts a hash of options:
-const myTour = new Shepherd.Tour(options);
-
-Tour Options
-
-steps: An array of Step instances to initialize the tour withdefaultStepOptions: Default options for Steps created through addSteptourName: An optional "name" for the tour. This will be appended to the the tour's
-dynamically generated id property -- which is also set on the body element as the data-shepherd-active-tour attribute whenever the tour becomes active.useModalOverlay: Whether or not steps should be placed above a darkened modal overlay. If true, the overlay will create an opening around the target element so that it can remain interactive.confirmCancel: If true, will issue a window.confirm before cancellingconfirmCancelMessage: The message to display in the confirm dialog
-Tour Methods
-
-addStep(id, options): Creates a new Step object with options, and returns the Step instance it created. If you'd like you can also just pass an options hash which includes id as a key.
-If the options hash doesn't include an id, one will be generated.
-You can also pass an existing Step instance rather than options, but note that Shepherd does not support a Step being attached to multiple Tours.getById(id): Return a step with a specific idnext(): Advance to the next step, in the order they were addedback(): Show the previous step, in the order they were addedcancel(): Trigger cancel on the current step, hiding it without advancinghide(): Hide the current stepshow([id]): Show the step specified by id (if it's a string), or index (if it's a number) provided. Defaults to the first step.start(): Show the first step and begin the tourgetCurrentStep(): Returns the currently shown stepon(eventName, handler, [context]): Bind an eventoff(eventName, [handler]): Unbind an eventonce(eventName, handler, [context]): Bind just the next instance of an event
-Tour Events
-
-complete: Triggered when the last step is advancedcancelhideshow: Triggered with a hash of the step and the previous stepstart
-Steps are instances of the Step object. They are generally created by the Tour::addStep method, which returns the Step instance it
-created.
-Steps
-Step Options
-
-text: The text in the body of the step. It can be one of three types:
-
-- HTML string
-HTMLElement objectFunction to be executed when the step is built. It must return one the two options above.
-title: The step's title. It becomes an h3 at the top of the step.attachTo: What element the step should be attached to on the page.
-It should be an object with the properties element and on, where element is an element selector string
-or a DOM element and on is the optional direction to place the Tippy tooltip.
-const new Step(tour, {
- attachTo: { element: '.some .selector-path', on: 'left' },
- ...moreOptions
-});
-
-If you don’t specify an attachTo the element will appear in the middle of the screen.
-If you omit the on portion of attachTo, the element will still be highlighted, but the tooltip will appear
-in the middle of the screen, without an arrow pointing to the target.
-
-beforeShowPromise: A function that returns a promise. When the promise resolves, the rest of the show code for
-the step will execute. For example:beforeShowPromise: function() {
- return new Promise(function(resolve) {
- $('#my-bootstrap-modal').on('shown.bs.modal', function () {
- resolve();
- });
- });
-},
-
-classes: A string of extra classes to add to the step's content element.buttons: An array of buttons to add to the step. These will be rendered in a footer below the main body text. Each button in the array is an object of the format:
-
-text: The HTML text of the buttonclasses: Extra classes to apply to the <a>action: A function executed when the button is clicked onevents: A hash of events to bind onto the button, for example {'mouseover': function(){}}. Adding a click event to events when you
-already have an action specified is not supported.
-You can use events to skip steps or navigate to specific steps, with something like:
-events: {
- click: function() {
- return Shepherd.activeTour.show('some_step_name');
- }
-}
-
-advanceOn: 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.
-For example: {selector: '.some-element', event: 'click'}. It doesn't have to be an event inside the tour, it can be any event fired on any element on the page.
-You can also always manually advance the Tour by calling myTour.next().highlightClass: 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.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.when: You can define show, hide, etc events inside when. For example:
-when: {
- show: function() {
- window.scrollTo(0, 0);
- }
-}
-
-
-Step Methods
-
-show(): Show this stephide(): Hide this stepcancel(): Hide this step and trigger the cancel eventcomplete(): Hide this step and trigger the complete eventscrollTo(): Scroll to this step's elementisOpen(): Returns true if the step is currently showndestroy(): Remove the elementon(eventName, handler, [context]): Bind an eventoff(eventName, [handler]): Unbind an eventonce(eventName, handler, [context]): Bind just the next instance of an event
-Step Events
-
-before-showshowbefore-hidehidecompletecanceldestroy
-Please note that complete and cancel are only ever triggered if you call the associated methods in your code.
-Advancing on Actions
-You can use the advanceOn option, or the Next button, to advance steps. If you would like however to have a step advance on a
-complex user action, you can do the following:
-const myStep = myTour.addStep('my-step', options);
-
-yourApp.on('some-event', () => {
- if (myStep.isOpen()){
- Shepherd.activeTour.next();
- }
-});
-
-It's strongly recommended that you use some sort of event mediator to connect your app's actions with Shepherd, to prevent
-having to sprinkle Shepherd code throughout your codebase, and to keep things loosely coupled. You can create a basic
-mediator if need be using the Evented object which is provided with Shepherd:
-const mediator = new Shepherd.Evented();
-
-You can then trigger events in one part of your app:
-mediator.trigger('user-create');
-
-And listen for them in other areas:
-mediator.on('user-create', () => {});
-
-Rendering Tours in Specific Locations
-By default, tour steps will append their elements to the body element of the DOM. This is perfect for most use cases, but not always. If you need to have steps appended elsewhere you can take advantage of Tippy's
-appendTo option by defining it on the
-tippyOptions hash inside of each Step's options hash.
-🔼 Displaying Arrows
-By default, Shepherd will generate and position an "arrow" element that points to the target
-of a step. This is done by setting Tippy's arrow option to true on each ``Step.options.tippyOptions` — but you can disable the arrow manually by setting it to false:
-myTour.addStep('Step 1', {
- tippyOptions: {
- arrow: false
- }
-});
-
-Furthermore, while each of Shepherd's themes provides some basic arrow styling, you can style it as you wish by targeting the markup that's genereated by Tippy.
-
-
-
-
