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
andsuppress
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 identifiermessage
: (string) Tip contentindex
: (number) Index at which to show the tipelement
: (DOM element) HTML element associated with the tip
Related
- ui-tourtip UI Component
- ui.tourtips client-side message
$core_v2_tourTip.Render
Widget API