Warning
step-manageris deprecated and has been merged into thecostrojsproject. See Costrojs for its successor 🎉
StepManager is a library to create flexible and robust multiple steps navigation with hash, validations, browser storage and hook functions.
The library is available as the step-manager package name on npm.
npm i --save-dev step-manageryarn add --dev step-managerOnline demo is available on yoriiis.github.io/step-manager
The project also includes an example of an implementation of StepManager in the directory ./example/.
StepManager is composed by the Manager to manage the steps and the Steps to create 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:
String
The route identifier is an alias to be used inside the app instead of the route.
The parameter is a public instance field.
String
The route for the step navigation. StepManager uses hashes for steps navigation (#people).
The parameter is a public instance field.
String
The CSS selector used in the template to identify the step.
The parameter is a public instance field.
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.
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
}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.
Function
The function returns the data for the template.
Function
The function allows to extract step data to save in the browser storage in order to persist during the entire navigation.
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.
HTMLElement
The HTML element where the manager will build the steps.
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.
Array
The array of steps.
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.
String
The browser storage method used by the manager (sessionStorage or localStorage).
String
The unique storage key to store the data in the browser storage.
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.
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.
The Manager exposes following functions.
The init() function initializes the manager and builds the steps.
manager.init();The destroy() function destroys the event listeners and the HTML.
manager.destroy();The isReverseNavigation() function checks if the navigation is reversed. The function can be called inside the onChange function.
manager.Router.isReverseNavigation()The getRouteId() function returns the routeId of the route.
manager.Router.getRouteId()The currentRoute property returns the current route.
manager.Router.currentRouteStepManager and its documentation are licensed under the MIT License.
Created with ♥ by @yoriiis.