Page Wizard

Page Wizard is a customisable wizard tool to guide users around the areas and features of the current web page, with accompanying text for each step. Check out the demo.

The elements to highlight are denoted in a data file (or data object passed to the function). Each element is highlighted and described sequentially, with a dark screen blacking out other page elements for the duration of the highlight.

Installation 🔗

You can load Page Wizard via a script tag or as an import, locally or from CDN.

import './page-wizard.js';
//or
import 'https://cdn.jsdelivr.net/gh/mitya33/page-wizard@latest/page-wizard.js';

API 🔗

To initiate Page Wizard call pageWizard(params) , where params is an object of params as follows:

dataFileUri (string) - a URI path to a data file denoting the elements to highlight and info about them. See also the data param.
data (object) - instead of providing a path to a data file via the dataFileUri param, this param allows you to pass data directly, as a JS object.
cssFileUri (string) - a URI path to the Page Wizard CSS file. This wil be loaded only if and when Page Wizard runs. You can optionally load the CSS from CDN via this URL.
minWidth (integer) - a minimum viewport width (in pixels) under which Page Wizard will not run, even if called. This means you don't have to check for this yourself before calling the function.
mode (string) - the placement mode for the info area - either 'float' (default), where elements are described by a floating box next to/above/below them (whichever is the optimal position), or 'floor', where elements are described via a fixed page footer.
onEndReturnTo (string) - optionally describes the scrolltop position the page should return to after Page Wizard has finished (because in highlighting page elements the scrolltop position will change as it runs). Either 'top' to return to page top, or 'orig' to return to the starting scrolltop position.
prompt (string) - an optional prompt for the user before Page Wizard runs, giving the user the changes to decline the wizard experience before it runs. This should be the prompt text the user will be asked. The prompt will be shown either via the native confirm() or, if present, the Lightbox Library.
singular (string) - a selector to a single element, as listed in the data, for times when you want to highlight and describe a single part of the page, rather than all of it.
onEndCallback (function) - an optional callback function to run when Page Wizard completes.
onEndMessage (string) - an optional message to be shown when Page Wizard completes. This will show either via the native alert() or, if present, the Lightbox Library.

Check out the demo.

Data structure 🔗

The data file (as fed to the dataFileUri param), or the data object (as fed to the data param) should be an array containing objets, one per element to highlight, with each object in the following structure:

See the demo data file as an example.

{
    "selector": "#foo .bar",
    "title": "Some element",
    "text": "Some description about the element, etc., etc."
}

selector should target the element.

If it targets more than one element, the first will be used.

If the element is not found, or found to have display: none or visibility: hidden, it will be skipped.

CSS adjustments 🔗

You'll need to adjust the CSS selectors you use to target elements you wish to highlight. This is because when Page Wizard highlights an element, it picks it up out of the DOM and makes it a child of the body, so any styling that relies on hierarchy will be lost.

Page Wizard will transfer any ID on the highlighted element to a class, in the format .pwz-id-*, where * is the ID value. So for highlightable elements styled by ID-based selectors, extend your selectors to incorporate this class. Example:

#myElement p { color: white; }
/* ...becomes */
#myElement, .pwz-id-myElement { background: red; }
#myElement p, .pwz-id-myElement p { color: white; }

Page Wizard will also transfer any class(es) on the element to its highlighted equivalent, as well as the additional class .pwz-highlighted. This means if your highlightable element is styled simply via .foo { /* ... */ }, you don't need do anything, as the "foo" class will be retained. However if it's styled by a more complex selector referencing parents, you'll want to adjust it. Example:

.someClass { color: orange; }
div .foo .bar { background: blue; }
div .foo .bar img { width: 30px; }
/* ...becomes... */
.someClass { color: orange; } /* no change - selector doesn't reference hierarchy */
div .foo .bar, .pwz-highlighted.bar { background: blue; }
div .foo .bar img, .pwz-highlighted.bar img { width: 30px; }

Page Wizard can work in conjunction with my own Lightbox Library project, to handle any prompts to launch the wizard or not (see the prompt param) and end-of-wizard messages (the onEndMessage param).

This makes for a far nicer interface - however if Lightbox Library is not present in the environment, Page Wizard will default to using native modals instead.