Hazeline

A simple, lightweight, framework agnostic tutorial library for any web application.

Made with love in TypeScript, but works like a charm even with vanilla JS.

And yes, it works great with Angular!

Install

npm install --save hazeline

Usage

Hazeline is extremely configurable, but is also designed to work out of the box, providing its own graphical style.

If you don't want to customize any option and just run it, these are the only lines you need:

import {Hazeline} from 'hazeline';

const haze = new Hazeline();
haze.addSection({
    id: 'test',
    steps: [
        {
            elementSelector: '#input-1',
            text: 'This is an awesome input box'
        },
        {
            elementSelector: '#input-2',
            text: 'This is another awesome input box'
        }
    ]
});

haze.runTutorial('test');

The above code, will create a tutorial section that contains two steps.

Since your application could have multiple sections, your tutorial should too. A section, for Hazeline is a "container" of steps. These steps will be used to guide the user through the application once the tutorial is ran.

The only property required for the section beside the steps, is the id. Is a simple string property, and you can name it whatever you want. You will use this id later to start that section.

Next, we define the steps. Each step requires a elementSelector and a text properties.

The elementSelector property is a jQuery style selector for any element that exists on the page. Although we are using a jQuery style selector, Hazeline does not depend on jQuery.

The text propery is the actual text that will be rendered inside the lightbox that will be attached to the highlighted element. The text property can also be raw HTML since it is passed to the innerHTML property of the lightbox element.

Finally we call hazeline.runTutorial('test');. As you can see, we use the previously defined section id to start that section when starting the tutorial. That's it.

Customization

Hazeline provides two types of customization:

One designed to be set once, and never think about it again. This, in Hazeline is called globalOptions, and can be defined at a section level. These options you will pass, will override the default options, and will be used for all the steps.

One designed to be more dynamic, it uses the same exact structure as the global one, but can be set at a step level, and is called dynamicOptions. These options will work only for that step.

With the combination of these two kind of customizations, you can define default options for the whole section, and in case you need more specificity or something different for a particular step, you can set it.

For more detailed information on how deep you can go with the customization see customization details.

Example of global customization

haze.addSection({
    id: 'test',
    steps: [
        {
            elementSelector: '#input-1',
            text: 'This is an awesome input box'
        },
        {
            elementSelector: '#input-2',
            text: 'This is another awesome input box'
        }
    ],
    globalOptions: {
        overlay: {
            closeBtnText: 'Quit',
            overlayCSS: {
                background: 'rgba(255, 255, 255, .85)'
            }
        },
        lightbox: {
            nextBtnText: '>',
            prevBtnText: '<',
            lightboxNextBtnCSS: {
                border: 'none'
            },
            lightboxPrevBtnCSS: {
                border: 'none'
            },
            lightboxWrapperCSS: {
                boxShadow: '0px 3px 12px -5px #333'
            }
        }
    }
});

Example of dynamic customization

The same logic applies for the steps, same options available:

haze.addSection({
    id: 'test',
    steps: [
        {
            elementSelector: '#input-1',
            text: 'This is an awesome input box',
            dynamicOptions: {
                overlay: {
                    closeBtnText: 'Quit',
                    overlayCSS: {
                        background: 'rgba(255, 255, 255, .85)'
                    }
                },
                lightbox: {
                    nextBtnText: '>',
                    prevBtnText: '<',
                    lightboxNextBtnCSS: {
                        border: 'none'
                    },
                    lightboxPrevBtnCSS: {
                        border: 'none'
                    },
                    lightboxWrapperCSS: {
                        boxShadow: '0px 3px 12px -5px #333'
                    }
                }
            }
        },
    ],
});

As you can see I just moved the options from the global place to the dynamic place on the first step. The result is the same as above, since we have only one step.

Textual Overlay Mode

By default Hazeline uses a lightbox to describe an element that is highlighted. This means that the concerned element has some meaning to the user, or you just want to describe it and introduce its functions.

But what if you don't have a specific element to highlight or describe? Let's say that you just want to give a brief description about the whole section, or greet the user with a message, and then start the actual tutorial. But a lightbox and a hightlighted element in that scenario wouldn't be the best choice.

Instead, you could use the Textual Overlay. When defining the step required options (text, and elementSelector) you can optionally activate the useOverlayInsteadOfLightbox property. For this step, the lightbox won't appear, and no particular element will be highlighted, even though you've specified the element selector.

As the lightbox, and all the other Hazeline's components, even this one is designed to work out of the box, but still you can customize it like the others. For more detailed information about the Textual Overlay see its specific configuration

Delaying the start of a specific step

It might happen that you have something asyncronus running that must be completed before the next step can begin. This might be a navigation to another page, on wich the element that the step about to start uses is present.

In these kind of situations the section step offers another type of configuration called delayBeforeStart. It is a number, and can set the milliseconds to wait before the step actually begin.

NOTE: When you use the delayBeforeStart there are a few things to keep in mind:

1) The majority of the CSS customization is done internally and based on your global or dynamic configuration for the normal overlay

2) When activating the delayBeforeStart you must specify the delayText, which will be the text that will appear in the middle of the overlay. This text can be a simple 'Please wait...'. It also accepts HTML. Note that if you don't specify this information, the overlay will result empty and the tutorial might look like stuck to the user.

3) Lastly, when activating the delayBeforeStart, you also must provide a text color for the overlay text. Since the normal overlay that wraps around the highlighted element doesn't contain any text, there's nothig that ensures that the property isn't undefined.

Offsetting the highlited element wrapping

Hazeline by default applies a 10px of offset around the element that it wraps. And if offsets the vertical alignment of the lightbox by -10px too. If you'd like to change this behaviour, you can override these offsets. On the globalOptions.overlay as well as the dynamicOptions.overlay you will these properties:

• topSideWrapOffset
• leftSideWrapOffset
• rightSideWrapOffset
• bottomSideWrapOffset

They respectively apply offsets on the top, left, right and bottom wrappers. You can valorize them all, or just the ones you need to.

Note: that when changing the lightbox placement, you will also have to modify its offset. Since Hazeline by default places the lightbox under the element and uses by defauly -10px of offset, if you don't change that value in 10px or accordingly with your wrappers offsets, the lightbox may overlap by 10px your hightlighted element when positioned on top of it.

No offsets example

Default offset example (10px)

Custom offset example (20px)

Hazeline callbacks to events

Hazeline allows you to specify two different callbacks to two different events. This logic applies both to the sections and to the steps:

• onBeforeEnd
• onBeforeStart

onBeforeStart

This callback will be executed right before the startup of the tutorial in case it's set at a Section level. If it's specified at a Step level, it will be executed right before the step startup.

This callback will be converted into an Observable, and from it will start the pipeline of events inside Hazeline. If you don't specify a onBeforeStart a Promise that resolves immediatly will be used.

Note: this is the first step of the pipeline, and if something asyncronus will be executed inside, the tutorial or the step won't start until the promise resolves, try to not clutter this too much as it may result is bad user experience.

onBeforeEnd

This callback will be executed right before the tutorial definitive shutdown, or before the next step loading.

This callback will be converted into an Observable, and it will be called right before the last event in the pipeline, the definitive shutdown of the tutorial in case it's placed at a Section level, or the loading of the next step in case it's placed at a Step level. If you don't specify a onBeforeEnd a Promise that resolves immediatly will be used.

Note: this is the step before the last one in the pipeline, both for the Sections and the Steps pipelines, and if something asyncronus will be executed inside, the tutorial won't quit or the next step won't load until the promise resolves, but the quit button will be removed. Try to not clutter this too much as it may result is bad user experience.

Also remember to always resolve your promises.

Hazeline section step specific properties

These are the HazelineTutorialStep specific properties:

Hazeline section/step dynamic properties

Overlay

The overlay option, allows you to customize the overlay that surrounds the highlighted element.

Lightbox

The lightbox option, allows you to customize the box that is placed near the highlighted element, containing the Next and Previous buttons and the text for the section step.

General Properties:

Positioning Properties:

Textual Overlay

The textual overlay is the overlay that appears instead of the lightbox when you set useOverlayInsteadOfLightbox on the section step.

Hazeline methods

addSection

Adds a section to the sections available. Optionally can clear the previous sections when adding a new one.

Arguments:

Returns: void

clearSections

Clears all the tutorial sections

Takes no arguments

Returns: void

runTutorial

Runs a specific tutorial section, given the section id. It returns an Observable containing the Tutorial Status.

Arguments:

Returns: Observable<HazelineTutorialStatus>

Hazeline interfaces and enums

HazelineTutorialStatus

Type: Interface

interface HazelineTutorialStatus {
    status: HazelineTutorialStatuses;
    runningSection: HazelineTutorialSection;
    runningStepInSection: HazelineTutorialStep;
}

HazelineTutorialStatuses

Type: Enum

enum HazelineTutorialStatuses {
    started,
    stopped,
    errored
}

HazelineTutorialSection

Type: Interface

interface HazelineTutorialSection {
    id: string;
    steps: HazelineTutorialStep[];

    globalOptions?: HazelineOptions;

    onBeforeEnd?: () => Promise<boolean>;
    onBeforeStart?: () => Promise<boolean>;
}

HazelineOptions

Type: Interface

interface HazelineOptions {
    overlay?: HazelineOverlayOptions;
    lightbox?: HazelineLightboxOptions;
    textualOverlay?: HazelineTextualOverlayOptions;
}

HazelineOverlayOptions

Type: Interface

interface HazelineOverlayOptions {
    closeBtnText?: string;

    topSideWrapOffset?: number;
    leftSideWrapOffset?: number;
    rightSideWrapOffset?: number;
    bottomSideWrapOffset?: number;

    overlayCSS?: HazelineCSSRules;
    endTutorialBtnCSS?: HazelineCSSRules;
    endTutorialBtnHoverCSS?: HazelineCSSRules;
}

HazelineLightboxOptions

Type: Interface

interface HazelineLightboxOptions {
    nextBtnText?: string;
    prevBtnText?: string;
    lastStepNextBtnText?: string;
    lightboxWrapperCSS?: HazelineCSSRules;
    lightboxNextBtnCSS?: HazelineCSSRules;
    lightboxPrevBtnCSS?: HazelineCSSRules;
    lightboxTextWrapperCSS?: HazelineCSSRules;
    lightboxControlsWrapperCSS?: HazelineCSSRules;

    lightboxPrevBtnHoverCSS?: HazelineCSSRules;
    lightboxNextBtnHoverCSS?: HazelineCSSRules;

    positioning?: {
        offset?: string;
        attachment?: string;
        classPrefix?: string;
        targetOffset?: string;
        targetAttachment?: string;
        constraints?: ITetherConstraint[];
        classes?: { [className: string]: boolean | string };
    };
}

HazelineTextualOverlayOptions

Type: Interface

interface HazelineTextualOverlayOptions {
    hideButtons?: boolean;
    disableBgFadeIn?: boolean;
    disableTextFadeIn?: boolean;
    clickAnywhereForNextStep?: boolean;

    bgFadeInTimeInMs?: number;
    textFadeInTimeInMs?: number;

    overlayBgFadeInOpacity?: number;
    overlayParagraphFadeInOpacity?: number;

    overlayCSS?: HazelineCSSRules;
    paragraphCSS?: HazelineCSSRules;
    prevNextButtonsCSS?: HazelineCSSRules;
    prevNextButtonsHoverCSS?: HazelineCSSRules;
}

HazelineTutorialStep

Type: Interface

interface HazelineTutorialStep {
    text: string;
    elementSelector: string;
    
    delayText?: string;
    delayTextColor?: string;
    delayBeforeStart?: number;

    dynamicOptions?: HazelineOptions;
    useOverlayInsteadOfLightbox?: boolean;

    onBeforeEnd?: () => Promise<boolean>;
    onBeforeStart?: () => Promise<boolean>;
}

Upcoming features

• Custom event triggers. (attach an event to the element, that when fired may execute a custom callback and then trigger the next step automatically)

Dependencies

• rxjs: v6.3.3
• tether: v1.4.5

Help Hazeline grow

If you like this project please help me with your feedback, leave a star :) Found a bug? Want a feature? Want some help? Feel free to open a Issue on GitHub.

Versioning

We use SemVer for versioning.

Authors

• Caius Citiriga

License

This project is licensed under the MIT License.