tourTips JavaScript API Module

jQuery.telligent.evolution.tourTips

This module exposes the client API by which widgets can register tour tips to be available to a user. It also supports persisting read states, as well as notifying the UI of which registered tips should be rendered to the user (that haven't already been marked as read by the user).

Model

Overview

Tour tips are popups that are shown to the user within a guided tour the first time the user visits a page associated with elements on the page.
Tour tips are widget-specific, not-page specific. A user visiting a page containing widget types never encountered by the user before that also have tour tips will be presented with the tips in an ordered, guided tour with the options to mark each tip as read (marking) or to skip the tour and revisit later (suppressing).
A user's per-tip read state is persisted on the server as well as in localstorage to to more efficieintly determine the read-state on the next viewing.
Tips can be presented not only on the page's first load, but also at any time while the page is already rendered, to support scenarios where widgets load content dynamically that contains tips.

Registration and Rendering

Widgets register tips to be rendered on the client side through this API.
Though this module's register method can be used directly, it is more commonly called through the ui-tourtip UI Component which is, itself, more commonly rendered through the $core_v2_tourTip.Render Widget API.
Batches of tips that have been registered all within a short period of time are processed to determine which have not already been viewed by the user, using local storage caching, batched requests to the server for a set of tips, and server caching of those same tips' read states.
Tips that are determined to have not been marked as read are then raised within a ui.tourtips client-side message for rendering by the UI.
By default, a tour tip widget is provided which subscribes to the ui.tourtips message, handles the presentation of these unread tips, and consumes this module's mark and suppress methods for saving read state or skipping the tour. However the presentation of tips is intended to be customizable or completely replaceable by custom widgets.

Methods

register

Registers a tip to be potentially shown to the user, dependent upon whether local or server storage already indicates the tip being in an unread state for the user, and tip presentation not currently being suppressed.

$.telligent.evolution.tourTips.register(tip);

mark

Persists a tip's read state as read or unread, both on the server as well as in user-scoped client-side localstorage.

// Mark a tip as read
$.telligent.evolution.tourTips.mark(tipKey, true);

// Mark a tip as unread
$.telligent.evolution.tourTips.mark(tipKey, false);

suppress

Suppresses presentation of tour tips by suppressing the publishing of ui.tourtips client-side [messages](@messaging for the accessing user for the provided period of time

// suppress all unread tour tips from displaying for a given duration in milliseconds
 $.telligent.evolution.tourTips.suppress(milliseconds)

Tip objects contain:

key: (string) Unique tip identifier
message: (string) Tip content
index: (number) Index at which to show the tip
element: (DOM element) HTML element associated with the tip

ui-tourtip UI Component
ui.tourtips client-side message
$core_v2_tourTip.Render Widget API

Recommended