This package has been deprecated

Author message:

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

StepManager

StepManager is a library to create flexible and robust multiple steps navigation with hash, validations, browser storage and hook functions.

Installation

The library is available as the step-manager package name on npm.

npm i --save-dev step-manager

yarn add --dev step-manager

Demo

Online demo is available on yoriiis.github.io/step-manager

The project also includes an example of an implementation of StepManager in the directory ./example/.

How it works

StepManager is composed by the Manager to manage the steps and the Steps to create steps.

Steps

First, create the steps container with a selector easily accessible.

<div id="steps"></div>

Next, create the steps People and Planet for our example. All the steps need inheritance from Steps to access hook functions.

step-people.js

import { Steps } from "step-manager";

export default class StepPeople extends Steps {
    id = "people";
    route = "people";
    selector = ".step-people";

    canTheStepBeDisplayed () {
        return {
            canBeDisplayed: true
        };
    }

    getTemplate (datas) {
        return `<div class="step-people">${datas.title}</div>`;
    }

    getStepDatasToRender () {
        return {
            title: 'people'
        };
    }

    getDatasFromStep () {
        return {};
    }
}

step-planet.js

import { Steps } from "step-manager";

export default class StepPlanet extends Steps {
    id = "planet";
    route = "planet";
    selector = ".step-planet";

    canTheStepBeDisplayed () {
        return {
            canBeDisplayed: true
        };
    }

    getTemplate (datas) {
        return `<div class="step-planet">${datas.planet}</div>`;
    }

    getStepDatasToRender () {
        return {
            title: 'planet'
        };
    }

    getDatasFromStep () {
        return {};
    }
}

The manager exposes its options on every step. Options can be accessed with this.options. The inheritance of the Steps class exposes the following class fields:

id

String

The route identifier is an alias to be used inside the app instead of the route.

The parameter is a public instance field.

route

String

The route for the step navigation. StepManager uses hashes for steps navigation (#people).

The parameter is a public instance field.

selector

String

The CSS selector used in the template to identify the step.

The parameter is a public instance field.

optionalStep

Boolean

To declare if the step is optional and can be submitted without validation. The validation is set on the canTheStepBeDisplayed function.

The parameter is a public instance field and is optional.

canTheStepBeDisplayed

Function

To declare the display conditions of the step. Needs to return an object with the following keys:

return {
    canBeDisplayed: true // Boolean
}

If the step can't be displayed, the manager will redirect to the route of the first step depending on the steps' order. The optional key fallbackRoute allows to override this behavior.

return {
    canBeDisplayed: true, // Boolean
    fallbackRoute: 'people' // String
}

getTemplate

Function

The function returns the template as HTML string or HTMLElement for the step and exposes the return of the getStepDatasToRender function as parameter.

Template can be written with template literals (String) or with JSX (HTMLElement). The demo includes templates in both types for the example.

getStepDatasToRender

Function

The function returns the data for the template.

getDatasFromStep

Function

The function allows to extract step data to save in the browser storage in order to persist during the entire navigation.

Manager

Now that the steps are created, we will create the Manager to manage them.

import StepPeople from "./step-people";
import StepPlanet from "./step-planet";
import { Manager } from "step-manager";

const manager = new Manager({
    element: document.querySelector("#steps"),
    datas: {},
    steps: [StepPeople, StepPlanet],
    ignoredHash: [],
    onComplete: datas => {},
    onChange: action => {}
});

manager.init();

The Manager fields are explained below.

element

HTMLElement

The HTML element where the manager will build the steps.

datas

Object

The data for all the steps are stored in a JSON. The object key needs to match with the route id declared in each step.

If the steps are built with dynamic content from an API for example, the manager exposes the datas fields inside the steps with this.options.datas, from the render function.

See the SWAPI example in the ./example/ directory for the full implementation.

steps

Array

The array of steps.

ignoredHash

Array

The array of ignored hash.

Use this array to list the ignored hashs and prevent the manager from listening for specific hashs which can cause conflicts with steps navigation. For example the following use case will work:

• With an ignored hash triggered, nothing will be added to the current steps.
• When the user returns to the same hash, nothing will is added because the step already exists.
• When the user triggers step navigation when an ignored hash is set, the navigation will run normally and destroy/create steps.

cacheMethod

String

The browser storage method used by the manager (sessionStorage or localStorage).

keyBrowserStorage

String

The unique storage key to store the data in the browser storage.

onComplete

Function

The function is called when all the steps are completed. The function exposes as parameter the datas variable with all the steps data combined in a object. The key corresponds to each route id.

You can call an API to save the data or redirect the user.

onChange

Function -> Promise

The function allows to add a specific behavior during the step changes. The function is called 2 times per step change, on the destroy event and on the create event. The function exposes the action variable as parameter according to the state (destroy or create).

The function needs to return a Promise resolved as the example below. The Promise allows to add any behavior during the step changes, like a transition or an XHR.

new Manager({
    onChange: action => {
        return new Promise(resolve => {
            // Add here the scripts to be executed on the step changes
            // The setTimeout is an example to add a fake delay during the change of steps
            setTimeout(() => {
                resolve();
            }, 1000);
        });
    }
});

See the SWAPI example in the ./example/ directory for the transition behavior on the step changes.

Available methods

The Manager exposes following functions.

Init

The init() function initializes the manager and builds the steps.

manager.init();

Destroy

The destroy() function destroys the event listeners and the HTML.

manager.destroy();

isReverseNavigation

The isReverseNavigation() function checks if the navigation is reversed. The function can be called inside the onChange function.

manager.Router.isReverseNavigation()

getRouteId

The getRouteId() function returns the routeId of the route.

manager.Router.getRouteId()

currentRoute

The currentRoute property returns the current route.

manager.Router.currentRoute

Licence

StepManager and its documentation are licensed under the MIT License.

Created with ♥ by @yoriiis.