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

Step before start delay

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.

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;
}

HazelineOptions

Type: Interface

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

HazelineOverlayOptions

Type: Interface

interface HazelineOverlayOptions {
    closeBtnText?: string;
    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;
}

Upcoming features

• Margin offset on highlighted item
• Ability to attach events on:
  • onStepEnd()
  • onStepStart()
  • onSectionEnd()
  • onSectionStart()
  • onTutorialPrematureEnd()

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.