Zangdar Wizard
A JavaScript class to simply generate and handle HTML form wizards.
You can find a very simple demo at this link, and the API documentation here.
Getting started
Installation
To install Zangdar, you just have to download zangdar.min.js
in the dist
folder and add a script into your HTML page :
Your have to add this basic CSS to your styles too :
Basic usage
Here a basic HTML form with sections to separate wizard parts :
Next Previous Next Previous Send
And you just have to instanciate Zangdar with the selector of the form you wan't to handle :
document
And.. voilà ! You have a fully functional wizard ! :)
Options & Events
You can pass an object of options as second class parameter. This is very useful, especially for adding events to the wizard lifecycle.
List of properties here :
Name | Type | Default | Description |
---|---|---|---|
step_selector | String | [data-step] |
Wizard step section selector |
prev_step_selector | String | [data-prev] |
Wizard step previous button (or any element) selector |
prev_step_selector | String | [data-next] |
Wizard step next button (or any element) selector |
submit_selector | String | [type="submit"] |
Wizard form submit button selector |
active_step_index | Number | 0 |
Wizard active step index (useful to define active step on wizard instanciation) |
classes.form | String | zangdar__wizard |
Wizard form CSS class |
classes.prev_button | String | zangdar__prev |
Wizard previous button (or any element) CSS class |
classes.next_button | String | zangdar__next |
Wizard next button (or any element) CSS class |
classes.step | String | zangdar__step |
Wizard step section CSS class |
classes.step_active | String | zangdar__step__active |
Wizard active step section CSS class |
bypass_validation | Boolean | false |
Bypass native browser validation or user custom validation |
List of events here :
Name | Type | Default | Parameters | Description |
---|---|---|---|---|
onSubmit | Function | null |
{Event} e |
Wizard form custom submit handler (see example below) |
onStepChange | Function | null |
{WizardStep} step {Object} oldStep {Number} direction {HTMLFormElement} form |
method triggered when a step changes (see example below) |
onValidation | Function | null |
{WizardStep} step {NodeListOf} fields {HTMLFormElement} form |
method triggered on wizard step HTML validation (see example below) |
customValidation | Function | null |
{WizardStep} step {NodeListOf} fields {HTMLFormElement} form |
method triggered on wizard step HTML validation (see example below) |
Here there are examples for the events listed above :
const wizard = '#my-form' { e // Ajax call, custom form processing or anything you wan't to do here... return false } { const breadcrumb = this // this refers to Zangdar form wizard instance } { if step // ... // Here a treatment after HTML native validation... } { // Use the Formr library to validate fields (https://github.com/betaWeb/formr) const validator = form if step validator length'password' 3 20 length'confirm_password' 3 20 if !validator // ... return false return true //... }
Available methods, getters and setters
You can retrieve all available methods on the API documentation.
Zangdar object
Getters
currentIndex: number
Returns current wizard step index.
ZangdarcurrentIndex
steps: WizardStep[]
Returns an array of wizard steps.
const strps = Zangdarsteps
uniqueId: String
Returns the wizard instance unique id. Useful if you have more than one instance of the wizard on the page.
const wizard_uuid = ZangdaruniqueId
Setters
No setters currently available.
Methods
refresh(): Zangdar
Refresh the wizard instance. Useful to refresh the DOM (when steps order has changed, for example).
Fluent method : can be chained with other methods
Zangdar
destroy(): Zangdar
Remove all listeners and destroys the wizard instance.
Fluent method : can be chained with other methods
Zangdar
setOption(key: String, value: any): Zangdar
Set an instance' option. (you can retrieve the options list above).
Fluent method : can be chained with other methods
ZangdarZangdarZangdar
getStep(key: String|Number): WizardStep|null
Get a WizardStep instance via his index or his label property (data-label attribute).
// With step indexconst step1 = Zangdar // OR with step labelconst step_one = Zangdar
getFormElement(): HTMLFormElement
Get wizard HTML form element.
const form = Zangdar
getCurrentStep(): WizardStep|null
Get the current WizardStep instance.
const currentStep = Zangdar
removeStep(key: Number|String|WizardStep): WizardStep|null
Remove a step based on his index, label property (data-label attribute) or WizardStep instance.
const step = Zangdarconst removedIndex = Zangdar // you can refresh the wizard after the step removalZangdar
first(): Zangdar
Reveals first step.
Fluent method : can be chained with other methods
Zangdar
last(): Zangdar
Reveals last step.
Fluent method : can be chained with other methods
Zangdar
prev(): Zangdar
Reveals prev step.
Fluent method : can be chained with other methods
Zangdar
next(): Zangdar
Reveals next step.
Fluent method : can be chained with other methods
Zangdarnext
revealStep(key: Number|String|WizardStep): Zangdar
Reveal a single step based on his index, label property (data-label attribute) or WizardStep instance.
Fluent method : can be chained with other methods
try // With his index Zangdar // OR with his label (data-label attribute) Zangdar // OR event with a WizardStep instance const step = Zangdar // ... Zangdar catch e // Step not found
createFromTemplate(template: Object): Zangdar
Create a wizard from an existing form with a template which is describes it, according to the options passed on wizard instance creation. Useful to convert programmatically a HTML form into a powerful Zangdar wizard (by keeping only choosen fields).
Fluent method : can be chained with other methods
<!-- Gonna be "step_one" --> Name Email <!-- Gonna be "step_two" --> Password Confirm password <!-- Gonna be "step_three" --> Select your gender Select... Male Female Other Send
const wizard = '#my_form'const template = 'step_one': '.field__name' '.field__email' 'step_two': '.field__password' '.field__password_confirm' 'step_three': '.field__genre' wizard
The generated wizard HTML markup will be :
Name Email Next Password Confirm password Prev Next Select your gender Select... Male Female Other Send
getBreadcrumb(): Object
Returns an object representing the wizard breadcrumb with the label property as key, and the WizardStep as value.
const breadcrumb = Zangdar
TODO
- Finish Zangdar Available methods, getters and setters readme section
- Add WizardStep Available methods, getters and setters readme section
- Update gh-pages API docs