Tourguide.js
###### Simple, lightweight library for creating guided tours for your web, apps and more.
> A
tour guide is a person who provides assistance, information on cultural, historical and contemporary heritage to people on organized
tours and individual clients at educational establishments, religious and historical sites, museums, and at venues of other significant interest, attractions sites.
[https://en.wikipedia.org/wiki/Tour_guide ]
Examples
$3
Want to see how it works right away?
Try on JSFiddle
$3
You can look at some react examples here:
React examples .
Install Tourguide.js
``
`
Why do I need Tourguide.js
"So, how do I use it?"
how-tos , lengthy docs , and step-by-step guides , and yet, nothing seems to be enough.
Tourguide.js - a simple yet powerful explainer utility, designed to help you make the reply a little bit less painful. Because, let's face it - picture is worth a 1000 words:
Getting started
Tourguide.js
$3
Try on JSFiddle
$3
tourguide.min.js
, add it to your project libraries, and then include it on page:
`
`
$3
Webpack , Rollup ) import Tourguide.js like so:
`
`
Usage
Tourguide.js must be instantiated:
`
`
root?
: root element the tour steps will attach to; default is document.body
selector?: if you want to use content based tour approach you can use this option to specify the common selector for the tour steps; default is [data-tour]
animationspeed?: speed of all tour built-in animations; default is 120
padding?: additional padding to add to step highlighter; default is 5(px)
steps?>: if you choose to take JSON based tour approach provide use this property to provide the data; default is null
src?: if you want to load the tour from a remote URL you may specify it here; default is null
preloadimages?: if you want to preload images, you may set this attribute to true; default is false
restoreinitialposition?: if you want to restore the scroll position after the tour ended, you may set this attribute to true; default is true
colors: if you want to customize the color schema of this plugin, use the following properties; the object you passed in will be combine with default values. The defaults are:
`
`
keyboardNavigation?: if you want to enable keyboard navigation, use this attribute. each attribute can be number, string or object.
false.
keyCode : DEPRECATED
key
keyCode, altKey, metaKey, ctrlKey and etc.
`json
`
request?: if you want to load the tour from a remote URL you may provide request headers here
`
`
actionHandlers?>: optional array of custom step action handlers (see Handling tour actions for details)
contentDecorators?>: optional array of custom step decoration handlers (see Content decorators for details)
onStart?: callback function triggered when the tour starts
onStop?: callback function triggered when tour stops
onComplete?: callback triggered when tour completes
onStep?: callback triggered when a tour step is shown
$3
MVC approach in your application. Simply add tour descriptions to the HTML elements in your page template:
`
`
Tourguide.js as-is:
`
`
Step section.
$3
JSON notation:
`
[
{
"selector": null,
"step": 1,
"title": "Lets take a moment and look around Docsie library",
"content": "Click a button to advance to the next step of this tour.
"image": "https://somehost.com/image.jpeg"
},
{
"selector": "[data-component=library]:first-of-type",
"step": 2,
"title": "Shelf",
"content": "Just like a real library <mark>Docsie</mark> starts with <dfn>shelves</dfn>. Each <dfn>shelf</dfn> represnts a separate collection of ideas. You may think of them as individual websites, or website sections."
}
]
`
Tourguide.js passing your JSON as steps: property:
`
`
Step section.
$3
src as one of the Tourguide.js init params:
`
`
Step section.
$3
selector?: CSS selector used to find the target element (used on JSON based approach and Remote URL approach)*
step?: tour step sequence number (when using JSON as data source this property may be omitted)
title: tour step title
content: write the content
title and content support markdown language and content decorators (see Content decorators for details)
image?: tour step illustration
width?: step width in pixels (computed automatically by default)
height?: step height in pixels (computed automatically by default)
layout?: this property can be horizontal or vertical and causes the tour step to be oriented horizontally or vertically (the default is vertical, works only when image is defined)
placement?: optional hint on where to place a tour step in relation to the step target; may be one of the following:
overlay?: when set to false - hides step overlay (the default is true)
navigation?: when set to false - hides step control buttons (the default is true)
actions: an array of step actions to be rendered in step footer (see Handling tour actions for details)
? indicates the property is optional
Content decorators
`
`
Tourguide.ContentDecorator class:
`
`
match: either a plain string or a RegExp object identifying the decorator in text
decoratorFn: function decorator will call when match has been found
text: full text of the step content
matches>: an array of matches found in content text
`
`
step: complete current step object
context: complete tour object
$3
`
`
`
`
$3
`
Click the {fontsize,16,button} to see the {fontsize,20,result}"
`
fontsize and parse two variables: 16 and button. You may then use these in your decorator function:
`
${match.properties[1]}
`
Handling tour actions
`
`
action.label, and tour action may be one of the following:
`
`
Tourguide.ActionHandler class.
`
`
actionName is the name of your action that must match with the action property to passed in your Action array. For instance if you pass {label: "Custom", action: "custom"} you must then pass the following action handler as part of your tour initialization options
`
`
$3
`
`
`
`
Controlling the tour
$3
`
`
$3
$3
$3
$3
`
`
$3
tourguide.currentstep: returns the current step object
tourguide.length: return the number of steps on the tour
tourguide.steps: returns the tour steps as JSON notation
tourguide.hasnext: return true if there are steps remaining in the tour, otherwise returns false
tourguide.options: returns Tourguide.js options object
Attaching callbacks
Tourguide.js supports several helpful callbacks to help you better control the tour. You may optionally pass the callback functions into the tour instance at initialization time:
`
onStart:function(options){...},
onStop:function(options){...},
onComplete:function(){...},
onStep:function(currentstep, type){...},
`
$3
options: tour options object
$3
options: tour options object
$3
$3
currentstep: tour step object
type: string representing the current direction of the tor; can be one of: "previous" | "next"
Step object
target: returns the target element step is attached to
el: returns the step view element
show(): show step element
hide(): hide step element
tourguide.currentstep property:
`
``
License
Tourguide.js is licensed under BSD 3-Clause "New" or "Revised" License