When the content of a web page is greatly adjusted, it often needs a navigation function to tell users that a certain function has been adjusted to another location. The normal way is to add a mask, highlight the adjusted area, and then use the text to complete the guidance. We call this function "guide", while Smartour pulls out the function of this guide and provides an out of the box solution.

Project address: https://github.com/jrainlau/s...

Official example: https://jrainlau.github.io/sm...

install

Smartour is built as a umd module, allowing users to introduce it in different 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()

Configuration item

Smartour() Is a build function that accepts a options Object as its configuration item.

{
  // `maskStyle 'is the style of guide mask
  // The default value will be overlapped with the configured value, and the configured content can override the default value.
  markStyle: `
    position: fixed;
    box-shadow: 0 0 0 9999px rgba(0, 0, 0, .5);
    z-index: 9998;
  `, // Default value

  // `slotStyle 'is the style of guided introduction
  // The default value will be overlapped with the configured value, and the configured content can override the default value.
  slotStyle: `
    position: fixed;
    z-index: 9999;
  }` // Default value

  // `maskPadding ` set the inner margin of the highlighted area
  maskPadding: { vertical: 5, horizontal: 5 }, // Default (vertical, horizontal)

  // `slotPosition 'set the location of the guide introduction
  // The options are: 'top', 'top right', 'top left', 'bottom', 'bottom right', 'bottom left'
  slotPosition: 'bottom', // Default value

  // `How to trigger maskEventType 'navigation mask event
  // The options are 'click', 'mouseon', 'mouseover', 'mousedown', 'mousemove', 'mouseup', 'touchstart', 'touchmove', 'touchend'
  maskEventType: 'click', // Default value

  // `Mask event
  maskEvent: () => {} // Default value

API

• queue(TourList)

  .queue() Accept one TourList parameter, This parameter contains some columns TourListItem The array.

  [{
    // `el 'is the CSS selector of the element to be highlighted
    el: '#id-1',
  
    // `slot 'is the html string of the navigation content
    slot: `
      <p>This is a demo...<p>
      <button class="key-1">Cancel</button>
      <button class="key-2">OK</button>
    `,
  
    // `keyNodes' defines the html node of the navigation content and the events it binds.
    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() Method to show the next tour. It returns a Smartour Instance Promise.

  const tour = new Smartour().queue(TourList)
  
  await tour.next() // Show the first tour
  await sleep(2000) // Delay 2 seconds
  await tour.next() // Show the second guide

• prev()

  .prev() Method to show the previous tour. It returns a Smartour Instance Promise.

  const tour = new Smartour().queue(TourList)
  
  await tour.next() // Show the first tour
  await sleep(2000) // Delay 2 seconds
  await tour.next() // Show the second guide
  await sleep(2000) // Delay 2 seconds
  await tour.prev() // Redisplay the first tour

• over()

  .over() Used to remove all guides.

  const tour = new Smartour().queue(TourList)
  
  await tour.next() // Show the first tour
  await sleep(2000) // Delay 2 seconds
  
  tour.over() // Remove all guides

• reset(options)

  Reset configuration items for the Smartour instance.

  const tour = new Smartour().queue(TourList)
  
  await tour.next() // Show the first tour
  await sleep(2000) // Delay 2 seconds
  
  tour.reset({
    maskStyle: `
      border-radius: 5px; // Fillet highlighted areas
    `
  })
  tour.next() // Show next tour

Use example

as Official example , its Smartour usage is as follows:

<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)
    }
  }]
}])

tour.next()

certificate

MIT