Smartour

Once a website has changed its UI, usually they would set a list of tour guide to tell the visitors, that some modules were moved to the other places. We named it as "tour guide", and Smartour is a solution for making tour guide much easier.

See live demo here: https://jrainlau.github.io/smartour

Install

Smartour was built to an umd and es modules package.

npm install smartour

/* ES Modules */
import Smartour from 'smartour/dist/index.esm.js'
/* CommandJS */
const Smartour = require('smartour')
/* <script> */
<script src="smartour/dist/index.js"></script>

Basic usage

Smartour provides a very simple API focus(), it's the easist way to highlight an element.

let tour = new Smartour()

tour.focus({
  el: '#basic-usage'
})

Slot

slot is a html string that allows you to add a description to the highlighted element.

Pure string:

let tour = new Smartour()

tour.focus({
  el: '#pure-string',
  slot: 'This is a pure string'
})

Html string

let tour = new Smartour()

tour.focus({
  el: '#html-string',
  slot: `
    <div>
      <p>This is a html string</p>
    </div>
  `
})

Slot positions

There are 4 positions to place a slot: top, right, left, bottom.

Set the options.slotPosition attribute to overwrite the default top.

let tour = new Smartour()

tour.focus({
  el: '#slot-positions',
  slot: `top`,
  options: {
    slotPosition: 'top' // default is `top`
  }
})

Slot events

The slot element could bind events, too. We can use the keyNodes attribute to bind events to them.

keyNodes is an array contains with keyNode. The attribute keyNode.el is a css selector, and the other keyNode.event is the binding event.

let tour = new Smartour()

tour.focus({
  el: '.slot-events-demo',
  options: {
    slotPosition: 'right'
  },
  slot: `
    <button class="demo-btn occur-1">
      Click here to occur an alert event
    </button>
    <button class="demo-btn occur-2">
      Click here to occur an alert event
    </button>
  `,
  keyNodes: [{
    el: '.occur-1',
    event: () => { alert('Event!!') }
  }, {
    el: '.occur-2',
    event: () => { alert('Another event!!') }
  }]
})

Queue

Sometimes there are more than one tour guide to show. Smartour allows you to put the tour guides together as a queue and show them one by one.

let tour = new Smartour()

tour
  .queue([{
    el: '.li-1',
    options: {
      layerEvent: tour.next.bind(tour)
    },
    slot: 'This is the 1st line.'
  }, {
    el: '.li-2',
    options: {
      layerEvent: tour.next.bind(tour)
    },
    slot: 'This is the 2nd line.'
  }, {
    el: '.li-3',
    options: {
      layerEvent: tour.next.bind(tour)
    },
    slot: 'This is the 3rd line.'
  }])
  .run() // don't forget to trigger api `run()` to show the first tour guide

Options

Smartour is a constructor and receives an options parameter to overwrite the default.

Let's take a look at the default options:

{
  prefix: 'smartour', // class prefix
  padding: 5, // padding of the highlight area
  maskColor: 'rgba(0, 0, 0, .5)', // maskColor with alpha
  animate: true, // use animate while changing tour guides
  slotPosition: 'top' // default slot position
  layerEvent: smartour.over // events while clicking the layer
}

APIs

Besides .focus(), .queue() and .run(), Smartour alse privides two apis to handle the tour guide playing.

• .next(): Show the next tour guide. (Only work with .queue())

• .prev(): Show the previous tour guide. (Only work with .queue())

Principles of Smartour

Smartour uses api element.getBoundingClientRect() to detect the size and position of the target element, than place a rect element with box-shadow over it as the highlight area.

Because click events could not be triigered from the box-shadow area, Smartour place another transparent layer over the page, and bind layerEvent() to it to solve this problem.

The position of the highlight area and slot are absolute. Every time the page scrolled, the value of document.documentElement.scrollTop or document.documentElement.scrollLeft would be changed, and Smartour will use these values to correct the position.

License

MIT