HintFlow

A class which shows a user a series of educational Hint popups in a flow. Each hint in the flow is shown in sequence attached to a target element. The user can navigate through the hints using buttons or keyboard shortcuts (N for next, P for previous, S or ESCAPE to stop).

It must be configured with an array of hint configurations. Each configuration is a config object for a Hint. Each hint in the flow may be configured with content or title to show contextual information for its target:

new HintFlow({
    // Default configs to apply to all hints
    defaults : {
        modal : true
    },
    hints : [{
        // CSS selector to find the target element
        target  : '.b-tab-panel-tab[data-item-index="1"]',

        // Action to take when the 'Next' button is clicked
        nextAction : {
            click : '.b-tab-panel-tab[data-item-index="1"]'
        }

        // Config props for the displayed Hint popup
        title   : 'Change tab',
        content : 'Click here to move to the next tab',
        align   : 't-n'
    }, {
        target  : '.b-tabpanel .b-tabpanel-body :nth-child(2) input',
        title   : 'Change name',
        content : 'Enter the new name here',
        nextAction : {
              text : 'New name[Enter]'
        }
    }, {
        target  : '.b-button:contains(Save)',
        title   : 'Save',
        content : 'Click here to save the changes',
        nextAction : {
           click : '.b-button:contains(Save)'
        }
   }]
});

Each entry in the hints array of the HintFlow class should be an object with the following properties:

target: Required The target element to highlight, or a CSS selector to find the target element. If the target selector ends with a ?, the hint will be skipped if the target is not found. By default, the hint will be aligned to this element.
title: The title to display in the hint.
content: Required. The content to display in the hint.
align: The alignment of the hint relative to the target element. If this is specified as an AlignSpec object, the hint will be aligned to the target property of this object if present.
- target: The element to align to, or a CSS selector to find the element to align to.
nextAction: The action(s) to take when the 'Next' button is clicked. Properties may be:
- click: A CSS selector to find the target element to click.
- contextmenu: A CSS selector to find the target element to right click.
- dblclick: A CSS selector to find the target element to double click.
- type: A string to type into the target element.
- fn: A function to call when the hint is shown.
- drag: An object with the following properties:
  - target: The target element to drag, or a CSS selector to find the target element.
  - by: The distance to drag the target element, as an array of [dx, dy].
- waitFor: A CSS selector to wait for or the number of milliseconds to wait before continuing to the next hint.
- allowInteraction: Specify as true to allow the user to interact with the target element.
previousAction: The action(s) to take when the 'Previous' button is clicked.
autoNext: The number of milliseconds to wait before automatically moving to the next hint, or a CSS selector to find the target element to wait for.
highlightTarget: Specify as true to highlight the target element with a bright outline.
buttons: Overrides for buttons to show in the hint. This is an object which may contain the following properties:
- next: Override config for the 'Next' button
- previous: Override config for the 'Previous' button
- stop: Config to add a 'Stop' button. By default the dialog close, or typing S button is used.

Other properties (eg modal can be added to the object, and will be passed to the Hint instance.

Pressing N will navigate to the next hint. P will navigate to the previous hint. Pressing S or ESCAPE will stop the tutorial. These defaults can be changed by setting the keyMap property in the defaults object.

Hint

//<code-header>
fiddle.title = 'Hint';
//</code-header>
targetElement.style.flexDirection = 'column';
targetElement.style.alignItems = 'flex-start';
targetElement.style.alignContent = 'flex-start';

function runHints() {
    new HintFlow({
        defaults : {
            highlightTarget : true
        },
        hints : [
            {
                target  : 'button[data-ref="learnButton"]',
                title   : 'Run hints',
                content : 'Click here to restart hint flow',
                align   : 's-e'
            },
            {
                target  : '.hint-panel .b-tool',
                title   : 'Settings',
                content : 'Click here to open Panel settings',
                align   : 's-e'
            },
            {
                target          : '.hint-panel [data-ref="email"] .b-field-inner',
                title           : 'Email',
                content         : 'Enter your email here',
                align           : 't-b',
                highlightTarget : {
                    // Expand the target zone a little
                    inflate : 5
                }
            },
            {
                target  : '.hint-panel [data-ref="send"]',
                title   : 'Send mail',
                content : 'Send the mail',
                align   : {
                    align  : 'b-t',
                    offset : [0, -5]
                },
                highlightTarget : {
                    center : '#9c37eb',
                    ping   : true
                }
            }
        ]
    });
}

new Button({
    ref      : 'learnButton',
    appendTo : targetElement,
    cls      : 'learnButton',
    text     : 'Start lesson',
    onClick  : runHints
});

new Panel({
    cls      : 'hint-panel',
    title    : 'My Panel',
    width    : 600,
    height   : '20em',
    appendTo : targetElement,
    tools    : {
        settings : {
            cls     : 'b-icon-cog',
            tooltip : 'Panel settings'
        }
    },
    items : {
        email : {
            inputType : 'email',
            type      : 'textfield',
            label     : 'Email Address'
        }
    },
    bbar : {
        items : {
            send : {
                text : 'Send Message'
            }
        }
    }
});

Configs

defaults: HintConfig

An object containing configuration properties to be applied to all hints in the flow.

An example may be to set the modal property to true to make all hints modal, or to set up keyboard shortcuts for the flow:

new HintFlow({
    defaults : {
        modal  : true,
        keyMap : {
            'A' : 'next',
            'B' : 'previous',
            'C' : 'stop'
        }
    }
});

hints: HintConfig[]

The array of hint configurations to show in the flow.