geekwolverine / tour

Touring and on-boarding for javascript applications

Tour

A simple, minimalist touring and on-boarding library for javascript

Awesome Demo

Features

• Supports single page apps, and complex scrollable content
• Responsive & Intelligent
• Automagic Positioning
• Promise Driven Events & Hooks
• Tour does not manipulate or relayer your DOM elements in any way

Installation

Install via npm

$ npm install tour --save

or CDN

https://npmcdn.com/tour@latest/dist/tour.js https://npmcdn.com/tour@latest/dist/tour.css

Import JS and CSS

// ES6+
import Tour from 'tour'

// CommonJS
const Tour = require('tour').default

// Vanilla
var Tour = window.Tour.default

@import 'node_modules/tour/dist/tour.css'

Simple Usage

const myTour = {
	canExit: true,
	nextText: 'Proceed!',
	steps: [{
		target: '#first-element',
		content: 'This is the first step!',
	}, {
		target: '.some .other .element',
		content: 'Blah blah blah. I prefer to show up on the right.',
		placement: [ 'right', 'top', 'bottom', 'left' ],
	}, {
		target: '#menu-element',
		content: 'I guess this is a menu!',
	}, {
		target: '#last-element',
		content: 'It is over! :(',
	}],
};

Tour.start(myTour)
  .then(() => {
    console.log('Tour Finished!');
  })
  .catch(() => {
    console.log('Tour Interrupted!')
  });

Config

Defaults:

{
	canExit: false, // Can exit the tour or not (via an X button)
	padding: 5, // Padding around the highlighted element
	maxHeight: 120, // Max height of the tooltip box
	maxWidth: 250, // Max width of the tooltip box
	maskVisible: true, // Shows the mask
	maskVisibleOnNoTarget: false, // Shows a full page mask if no target element has been specified
	maskClickThrough: false, // Allows the user to interact with elements beneath the mask
	maskScrollThrough: true // Allows the user to scroll the scrollbox or window through the mask
	maskColor: 'rgba(0,0,0,.7)' // The mask color
	scrollBox: 'body', // The container to scroll when searching for elements
	previousText: 'Previous',
	nextText: 'Next',
	finishText: 'Finish',
	showPrevious: true, // Setting to false hides the previous button
	showNext: true // Setting to false hides the next button
	animationDuration: 400, // Animation Duration for the box and mask
	placement: ['bottom', 'right', 'top','left'],
	dark: false, // Dark mode (Works great with `mask.visible = false`)
	disableInteraction: false, // Disable interaction with the highlighted elements
	disableEscExit: false // Disable end of tour when pressing ESC,
}

API

.start(tour)

• Starts a Tour
• Params:
  • tour: Tour Object
• Returns:
  • Promise that resolves when the tour is finished or rejected when aborted.

.stop()

• Stops a Tour
• Returns:
  • Promise that resolves when the tour is stopped.

.next()

• Goes to the next step in the current tour
• Returns:
  • Promise that resolves when the next step is reached

.previous()

• Goes to the previous step in the current tour
  • Promise that resolves when the previous step is reached

.goto(index)

• Goes to a specific step in the tour

• Params:

  • index: The 0-index number of the step eg. 0, 1, 2, 3

• Returns:

  • Promise that resolves when the specific step is reached

Using Promise Event Hooks

You can pass any function that returns a promise to the before and after properties for any step. When the promise resolves, the tour moves on accordingly.

Example

var tour = {
	steps: [{
      target: '#first-element',
      content: 'This is the first step!',
    }, {
      target: '.some .other .element',
      content: 'Blah blah blah.',
      before: () => {
      	// Do something amazing
      	return new Promise()
    	}
    }, {
      target: '#menu-element',
      content: 'I guess this is a menu!',
      after: () => {
      	// Do some more cool stuff
      	return new Promise()
    	}
    }, {
      target: '#last-element',
      content: 'It is over! :(',
    }]
}

Roadmap & Contributing

All PR's and contributions are more than welcome!