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