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.
Github: https://github.com/jrainlau/smartour
Official demo: https://jrainlau.github.io/smartour
Usage
Smartour were built as an umd package, which means you can import it in many ways.
npm install smartour/* ES Modules */
import Smartour from 'smartour'
/* CommandJS */
const Smartour = require('smartour')
/* <script> */
<script src="smartour/dist/index.js"></script>const tour = new Smartour().queue([{
el: '#id',
slot: `
<p>Something you want to guide to the visitors</p>
`
}])
tour.next()
Options
The Smartour() is a class who recives an options parameter.
{
// `maskStyle` is the stylesheet of the mask.
// default value will be concated with the new defined.
markStyle: `
position: fixed;
box-shadow: 0 0 0 9999px rgba(0, 0, 0, .5);
z-index: 9998;
`, // default // `slotStyle` is the stylesheet of the slot content.
// default value will be concated with the new defined.
slotStyle: `
position: fixed;
z-index: 9999;
}` // default // `maskPadding` sets the padding within the highligt area
maskPadding: { vertical: 5, horizontal: 5 }, // default // `slotPosition` sets the position of the slot content
// 'top', 'top-right', 'top-left', 'bottom', 'bottom-right', 'bottom-left' are allowd.
slotPosition: 'bottom', // default // `maskEventType` event type of the trigger event binding to the mask
// 'click', 'mouseon', 'mouseover', 'mousedown', 'mousemove', 'mouseup', 'touchstart', 'touchmove', 'touchend' are allowd
maskEventType: 'click', //default // `maskEvent` is the event binding to the mask
maskEvent: () => {} // default
APIs
queue(TourList)
.queue() recieves a TourList parameter, which is a list contains one or more TourListItem.
[{
// `el` is the selector of the highlight element
el: '#id-1',
// `slot` is a html string of the guide content
slot: `
<p>This is a demo...<p>
<button class="key-1">Cancel</button>
<button class="key-2">OK</button>
`,
// `keyNodes` defines the binding relationship between events and slot
keyNodes: [{
el: '.key-1',
eventType: 'click',
event: (e) => {
alert('Click "Cancel" button')
}
}, {
el: '.key-2',
eventType: 'mouseover',
event: (e) => {
alert('Hover "OK" button')
}
}]
}]next()
.next() is a function to show the next tour guide, and returns a Promise which contains the Smartour instance.
const tour = new Smartour().queue(TourList)await tour.next() // shows the first tour guide
await sleep(2000) // 2s timeout
await tour.next() // shows the second tour guide
prev()
.prev() is a function to show the prev tour guide, and returns a Promise which contains the Smartour instance.
const tour = new Smartour().queue(TourList)await tour.next() // shows the first tour guide
await sleep(2000) // 2s timeout
await tour.next() // shows the second tour guide
await sleep(2000) // 2s timeout
await tour.prev() // shows the first tour guide again
over()
.over() is a function to remove all the guides.
const tour = new Smartour().queue(TourList)await tour.next() // shows the first tour guide
await sleep(2000) // 2s timeouttour.over() // all the guides were removed
reset(options)
Set a new options to the Smartour instance.
const tour = new Smartour().queue(TourList)await tour.next() // shows the first tour guide
await sleep(2000) // 2s timeouttour.reset({
maskStyle: `
border-radius: 5px;
`
})
tour.next()
Example
We use the official demo usage as an example.
<body>
<main>
<h1 class="title">Smartour</h1>
<h3 class="desc">Makes website guiding easier</h3>
<a class="link" href="https://github.com/jrainlau/smartour/blob/master/README.md#smartour">Document</a>
</main>
</body>const tour = new Smartour({
slotPosition: 'top',
maskStyle: `border-radius: 4px;`
}).queue([{
el: '.title',
slot: `
<div class="guide guide-1">
<p>This is my name!</p>
<button class="btn btn-1">OK.</button>
</div>
`,
keyNodes: [{
el: '.btn-1',
event () {
tour.reset({
slotPosition: 'bottom-right',
maskStyle: `border-radius: 4px;`
})
tour.next()
}
}]
}, {
el: '.desc',
slot: `
<div class="guide guide-2">
<p>This is what my job is!</p>
<button class="btn btn-2">Yeah.</button>
</div>
`,
keyNodes: [{
el: '.btn-2',
event () {
tour.reset({
slotPosition: 'bottom',
maskStyle: `border-radius: 4px;`
})
tour.next()
}
}]
}, {
el: '.link',
slot: `
<div class="guide guide-3">
<p>This is the document!</p>
<button class="btn btn-3">Got it.</button>
</div>
`,
keyNodes: [{
el: '.btn-3',
event () {
tour.over()
}
}]
}])tour.next()
License
MIT