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).
- 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
localstorageto 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
registermethod can be used directly, it is more commonly called through the ui-tourtip UI Component which is, itself, more commonly rendered through the
- 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
suppressmethods for saving read state or skipping the tour. However the presentation of tips is intended to be customizable or completely replaceable by custom widgets.
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.
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);
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)
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