Neoclassical Philosophic Musings

    step-manager

    1.2.2 • Public • Published

    StepManager

    StepManager GitHub Workflow Status (branch) Coverage Status Node.js

    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.

    Install

    npm i step-manager

    DownloadsWeekly Downloads

    5

    Version

    1.2.2

    License

    none

    Unpacked Size

    24.4 kB

    Total Files

    5

    Last publish

    Collaborators

    • yoriiis