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 = tour
Slot
slot
is a html string that allows you to add a description to the highlighted element.
Pure string:
let tour = tour
Html string
let tour = tour
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 = tour
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 = tour
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 = tour // 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: smartourover // 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