Global

Type Definitions

ChariotConfiguration

The master Chariot configuration dictionary can consist of multiple tutorial configurations.
Properties:
Name Type Description
config Object.<string, TutorialConfig> The main configuration containing all tutorials.
Source:

ChariotDelegate

The delegate optionally responds to lifecycle callbacks from Chariot.
Properties:
Name Type Description
delegate Object The object that responds to the following lifecycle callbacks.
  1. willBeginTutorial
  2. The following are repeated for each step.
    1. willBeginStep
    2. willRenderOverlay
    3. didShowOverlay
    4. willRenderTooltip
    5. didRenderTooltip
    6. didFinishStep
  3. didFinishTutorial
Source:

didFinishStep(step, stepIndex, tutorial) → {Promise}

Called once after each step is finished.
Parameters:
Name Type Description
step Step The current Step object
stepIndex int Index of current Step
tutorial Tutorial The Tutorial object corresponding to this Step
Source:
Returns:
[promise] Return a promise if you have async callbacks that must be resolved before continuing.
Type
Promise

didFinishTutorial(tutorial, forced)

Called once after a tutorial is finished.
Parameters:
Name Type Description
tutorial Tutorial The Tutorial object
forced boolean Indicates whether tutorial was forced to end
Source:

didRenderTooltip(tooltip, stepIndex, tutorial) → {Promise}

Called once after each tooltip is rendered.
Parameters:
Name Type Description
tooltip Tooltip The current Tooltip object
stepIndex int Index of current Step
tutorial Tutorial The Tutorial object corresponding to this Step
Source:
Returns:
[promise] Return a promise if you have async callbacks that must be resolved before continuing.
Type
Promise

didShowOverlay(overlay, stepIndex, tutorial) → {Promise}

Called once after each overlay is shown.
Parameters:
Name Type Description
overlay Overlay The current Overlay object
stepIndex int Index of current Step
tutorial Tutorial The Tutorial object corresponding to this Step
Source:
Returns:
[promise] Return a promise if you have async callbacks that must be resolved before continuing.
Type
Promise

handleHashChange()

Called when handling browser hashChange events.

The four delegate methods (handlePopState, handlePushState, handleReplaceState, handleHashChange) are called during browser navigation events. Routing libraries might use one or more of these methods to implement routing for single page applications.

The default handler for these events will force quit the current tutorial. If you choose to override any of these methods, you will be responsibile for calling `tutorial.end()`.

Source:

handlePopState()

Called when handling browser popState events.

The four delegate methods (handlePopState, handlePushState, handleReplaceState, handleHashChange) are called during browser navigation events. Routing libraries might use one or more of these methods to implement routing for single page applications.

The default handler for these events will force quit the current tutorial. If you choose to override any of these methods, you will be responsibile for calling `tutorial.end()`.

Source:

handlePushState()

Called when handling browser pushState events.

The four delegate methods (handlePopState, handlePushState, handleReplaceState, handleHashChange) are called during browser navigation events. Routing libraries might use one or more of these methods to implement routing for single page applications.

The default handler for these events will force quit the current tutorial. If you choose to override any of these methods, you will be responsibile for calling `tutorial.end()`.

Source:

handleReplaceState()

Called when handling browser replaceState events.

The four delegate methods (handlePopState, handlePushState, handleReplaceState, handleHashChange) are called during browser navigation events. Routing libraries might use one or more of these methods to implement routing for single page applications.

The default handler for these events will force quit the current tutorial. If you choose to override any of these methods, you will be responsibile for calling `tutorial.end()`.

Source:

StepConfiguration

The step configuration is where you specify which elements of the page will be cloned and placed over the overlay. These elements are the what appear as highlighted to the user.
Properties:
Name Type Attributes Description
tooltip TooltipConfiguration Tooltip configuration.
selectors Object.<string, string> | Array.<string> | string <optional>
 Object with arbitrarily-named keys and CSS selector values. These keys can then be referenced from TooltipConfiguration.anchorElement. Or, an array of selector strings if named keys are not required. Or, a string if only one selector is required. Notes: Specifying a selector that targets another specified selector will result in unpredictable behavior. Specifying multiple selectors will effectively cause Tutorial.useTransparentOverlayStrategy == false.
Source:

Tooltip-renderCallback(currentStep, totalSteps) → {string}

A function that provides step information and returns subtext content.
Parameters:
Name Type Description
currentStep number The current step number
totalSteps number The total # of steps
Source:
Returns:
markup - The HTML markup that represents the subtext
Type
string

Tooltip-subtextCallback(currentStep, totalSteps) → {string}

A function that provides step information and returns subtext content.
Parameters:
Name Type Description
currentStep number The current step number
totalSteps number The total # of steps
Source:
Returns:
markup - The HTML markup that represents the subtext
Type
string

TooltipConfiguration

The tooltip configuration allows you to specify which anchor element will be pointed to by the tooltip, along with its position. A default template is provided, which can be configured
Properties:
Name Type Attributes Description
position string Relatively positions the tooltip to the anchor element. Possible values: 'top' | 'left' | 'bottom' | 'right'
anchorElement string <optional>
 Optional if the corresponding Step contains only one selector. anchorElement can be either (1) a key from StepConfiguration.selectors above, or (2) a CSS selector
className string <optional>
 One or more space-separated classes to be added to the class attribute of each tooltip.
xOffsetTooltip number <optional>
 Value in pixels to offset the x-coordinate of the tooltip.
yOffsetTooltip number <optional>
 Value in pixels to offset the y-coordinate of the tooltip.
offsetArrow number <optional>
 Value in pixels to offset the arrow. If the position is top or bootom, this still offset the x coord. If left or right it will offset the y coord. If undefined or 0, arrow is centered.
render Tooltip-renderCallback <optional>
 (TODO) Renders a custom template, thereby ignoring all other properties below.
iconUrl string <optional>
 Path to an image displayed above the title.
title string <optional>
 The title text of a toolip.
body string | function <optional>
 The body text of a tooltip, or a callback that returns custom HTML.
cta string <optional>
 The text contained within the button.
attr Object <optional>
 HTML attributes to set on the tooltip.
arrowLength Number <optional>
 Distance between arrow tip and edge of tooltip, not including border. A value of 0 removes the arrow.
subtext Tooltip-subtextCallback <optional>
 Callback that returns subtext content.
Source:

TutorialConfiguration

The tutorial configuration is where the steps of a tutorial are specified, and also allows customization of the overlay style. If optional configuration parameters are not required, the steps property array can be passed in directly as the configuration.

Notes on implementation:

The elements defined in each step of a tutorial via StepConfiguration.selectors are highlighted using transparent overlays.

These elements areare overlaid using one of two strategies:

  1. Semi-transparent overlay with a transparent section cut out over the element
  2. Selected elements are cloned and placed above a transparent overlay

#1 is more performant, but issues arise when an element is not rectangularly- shaped, or when it has `:before` or `:after` pseudo-selectors that insert new DOM elements that protrude out of the main element.

#2 is slower because of deep CSS style cloning, but it will correctly render the entire element in question, regardless of shape or size.

However, there are edge cases where Firefox will not clone CSS `margin` attribute of children elements. In those cases, the delegate callbacks should be utilized to fix. Note however, that #2 is always chosen if multiple selectors are specified in StepConfiguration.selectors.

Properties:
Name Type Attributes Default Description
steps Array.<StepConfiguration> An array of step configurations (see below). Note that this property can be passed as the configuration if the optional params below are not used.
zIndex integer <optional>
 20 Sets the base z-index value used by this tutorial
shouldOverlay boolean <optional>
 true Setting to false will disable the overlay that normally appears over the page and behind the tooltips.
overlayColor string <optional>
 'rgba(255,255,255,0.7)' Overlay CSS color
onComplete Tutorial-onCompleteCallback <optional>
 Callback that is called once the tutorial has gone through all steps.
useTransparentOverlayStrategy boolean <optional>
 false Setting to true will use an implementation that does not rely on cloning highlighted elements. Note: This value is ignored if a step contains multiple selectors. useTransparentOverlayStrategy is named as such because
animated boolean <optional>
 false (TODO) Enables spotlight-like transitions between steps.
Source:

willBeginStep(step, stepIndex, tutorial) → {Promise}

Called once before each step begins. Return a promise here if you have async callbacks you want resolved before continuing.
Parameters:
Name Type Description
step Step The current Step object
stepIndex int Index of current Step
tutorial Tutorial The Tutorial object corresponding to this Step
Source:
Returns:
[promise] Return a promise if you have async callbacks that must be resolved before continuing.
Type
Promise

willBeginTutorial(tutorial)

Called once before a tutorial begins.
Parameters:
Name Type Description
tutorial Tutorial The Tutorial object
Source:

willRenderTooltip(tooltip, stepIndex, tutorial) → {Promise}

Called once before each tooltip is rendered.
Parameters:
Name Type Description
tooltip Tooltip The current Tooltip object
stepIndex int Index of current Step
tutorial Tutorial The Tutorial object corresponding to this Step
Source:
Returns:
[promise] Return a promise if you have async callbacks that must be resolved before continuing.
Type
Promise

willShowOverlay(overlay, stepIndex, tutorial) → {Promise}

Called once before each overlay is shown.
Parameters:
Name Type Description
overlay Overlay The current Overlay object
stepIndex int Index of current Step
tutorial Tutorial The Tutorial object corresponding to this Step
Source:
Returns:
[promise] Return a promise if you have async callbacks that must be resolved before continuing.
Type
Promise