guideline

New Features Guideline (新功能指引)

This is a simple guideline tool based on which you can quickly implement new features guidelines for website users.

Usage

There are two ways to play a guideline, a simple way and an advanced way. The simple way is an encapsulation of the advanced way which can do more setting and control the playing of guideline.

Guideline also supports using keyboard shortcuts to control playback. See the relevant part of API for details

Simple way

const guideline = require('guideline');
 
const visitTimes = parseInt(localStorage.getItem('visitTimes')) || 0;
 
if (visitTimes === 0) {
  const guideOptions = [{
    content: 'Welcome, the new features guidelines come online !'
  }, {
    element: document.getElementById('notificationwrapper'),
    content: 'all system messages and notification is here',
    style: 'font-size: 20px; color: red;',
    position: 'top'
  }, {
    element: document.querySelector('.datepicker-hint'),
    content: 'datepicker hint will tell you the datepicker\'s date range restriction',
    position: 'bottom'
  }];
 
  guideline(guideOptions, function () {
    console.log('guideline is over');
  });
}

Advanced way

const guideline = require('guideline');
 
// something else ...
 
const guideOptions = [{
  content: 'Welcome, the new features guidelines come online !'
}, {
  element: document.getElementById('notificationwrapper'),
  content: 'all system messages and notification is here',
  style: 'font-size: 20px; color: red;',
  position: 'top'
}, {
  element: document.querySelector('.datepicker-hint'),
  content: 'datepicker hint will tell you the datepicker\'s date range restriction',
  position: 'bottom'
}];
 
const gl = new guideline.Guideline(guideOptions, function (total, played) {
  console.log('guideline is over, total valid ', total, 'played ', played);
});
 
// set hint text maximum width
gl.hintTextMaxWidth = 800
// set hint text font size
gl.hintFontSize = 20
 
// start the guideline
gl.play();
 
// autoplay the next hint every 3 seconds
const timer = setInterval(function () {
  if (gl.hasNext()) {
    gl.next();
  } else {
    clearInterval(timer);
    gl.stop();
  }
}, 3000);

API

guideline(configuration, callback)

This is the simple way to play a guideline which accepts two parameters whose description are listed in the relevant sections as follows.

guideline.Guideline Constructor (configuration, callback)

This is the advanced way to play a guideline which parameters are the same as guideline(configuration, callback). It will return a Guideline instance based on whose prototype's method you can do more control during the playing.

configuration - guideline(configuration)

The configuration item should be an array, each of which is an object.

Configuration Subitem Object

Properties:

• element (HTMLElement, optional) : the guided element. when element is null, the guideline text is centered relative to the browser window.
• content (string, required) : the guideline text.
• position (string, optional, defaults to 'bottom') : used to set the location of the guideline text relative to the guided element. enumerated type，value is 'top' or 'bottom'.
• style (string, optional) : custom style for the guideline text.

callback(total, playedAmount) - guideline(configuration, callback)

callback is a function, which will be invoked when the guideline stops. callback takes two parameters total and playedAmount, representing the total amount of valid hints and the actual playback amount of hints.

Guideline instance properties

• hintTextMaxWidth (number, defaults to 400) : used to limit the hint text maximum width, unit is pixel.
• hintFontSize (number, defaults to 24) : used to define the hint text font size, unit is pixel.

Guideline instance method

• play : start the guideline after doing some settings
• prev : play the previous hint
• next : play the next hint, if there's no more hint, stop the guideline and exit
• hasNext : tell if there is a follow-up hint
• stop : stop playing the guideline

Keyboard shortcuts

Guideline supports some keyboard shortcuts to play the next or previous hint as follows.

keyboard	action
arrow right	play next
enter	play next
space	play next
arrow left	play previous
backspace	play previous
esc	stop playing

License

MIT