Skip to content

Latest commit

 

History

History
461 lines (342 loc) · 12 KB

README.md

File metadata and controls

461 lines (342 loc) · 12 KB
Raw

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 :

<script src="path/to/zangdar.min.js"></script>

Your have to add this basic CSS to your styles too :

.zangdar__wizard .zangdar__step {
    display: none;
}
.zangdar__wizard .zangdar__step.zangdar__step__active {
    display: block;
}

Basic usage

Here a basic HTML form with sections to separate wizard parts :

<form id="my-form">
    <section data-step="coords">
        <input type="text" name="name" placeholder="Your name here...">
        <input type="text" name="email" placeholder="Your email here...">
        
        <button data-next>Next</button>
    </section>
    
    <section data-step="security">
        <input type="password" name="password" placeholder="Your password here...">
        <input type="password" name="password_confirm" placeholder="Confirm your password here...">
        
        <button data-prev>Previous</button>
        <button data-next>Next</button>
    </section>
    
    <section data-step="personal">
        <input type="date" name="birthdate" placeholder="Your birthdate...">
        <input type="text" name="addresss" placeholder="Your address here...">
        <input type="number" name="zipcode" placeholder="Your zipcode here...">
        <input type="text" name="city" placeholder="Your city here...">
        
        <button data-prev>Previous</button>
        <button type="submit">Send</button>
    </section>
</form>

And you just have to instanciate Zangdar with the selector of the form you wan't to handle :

document.addEventListener('DOMContentLoaded', () => {
    const wizard = new Zangdar('#my-form')
})

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 = new Zangdar('#my-form', {
    onSubmit(e) {
        e.preventDefault()
        
        // Ajax call, custom form processing or anything you wan't to do here...
        
        return false
    },
    
    onStepChange(step, oldStep, direction, form) {
        const breadcrumb = this.getBreadcrumb() // this refers to Zangdar form wizard instance
    },
    
    onValidation(step, fields, form) {
        if (step.hasErrors()) {
            // ...
        }
        // Here a treatment after HTML native validation...
    },
    
    customValidation(step, fields, form) {
        // Use the Formr library to validate fields (https://github.com/betaWeb/formr)
        const validator = new Formr(form)
        if (step.labeled('...')) {
            validator
                .required('name', 'email', 'password', 'confirm_password')
                .string('name', 'email', 'password', 'confirm_password')
                .email('email')
                .length('password', 3, 20)
                .length('confirm_password', 3, 20)
                .same('password', 'confirm_password')
                .validateAll()
                
             if (!validator.isValid()) {
                 // ...
                 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.

Zangdar.currentIndex

  • steps: WizardStep[]

Returns an array of wizard steps.

const strps = Zangdar.steps

  • 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 = Zangdar.uniqueId



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.refresh()

  • destroy(): Zangdar

Remove all listeners and destroys the wizard instance.

Fluent method : can be chained with other methods

Zangdar.destroy()

  • 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

Zangdar.setOption('active_step_index', 3)
Zangdar.setOption('bypass_validation', true)
Zangdar.refresh()

  • getStep(key: String|Number): WizardStep|null

Get a WizardStep instance via his index or his label property (data-label attribute).

// With step index
const step1 = Zangdar.getStep(1)

// OR with step label
const step_one = Zangdar.getStep('one')

  • getFormElement(): HTMLFormElement

Get wizard HTML form element.

const form = Zangdar.getFormElement()

  • getCurrentStep(): WizardStep|null

Get the current WizardStep instance.

const currentStep = Zangdar.getCurrentStep()

  • removeStep(key: Number|String|WizardStep): WizardStep|null

Remove a step based on his index, label property (data-label attribute) or WizardStep instance.

const step = Zangdar.getStep('step_six')
const removedIndex = Zangdar.removeStep(step)

// you can refresh the wizard after the step removal
Zangdar.refresh()

  • first(): Zangdar

Reveals first step.

Fluent method : can be chained with other methods

Zangdar.first()

  • last(): Zangdar

Reveals last step.

Fluent method : can be chained with other methods

Zangdar.last()

  • prev(): Zangdar

Reveals prev step.

Fluent method : can be chained with other methods

Zangdar.prev()

  • next(): Zangdar

Reveals next step.

Fluent method : can be chained with other methods

Zangdar.next()

  • 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.revealStep(3)
	
	// OR with his label (data-label attribute)
	Zangdar.revealStep('step_three')
	
	// OR event with a WizardStep instance
	const step = Zangdar.getStep('step_three')
	// ...
	Zangdar.revealStep(step)
} 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

<form id="my_form">
	<!-- Gonna be "step_one" -->
	<div class="field__name">
		<label for="name">Name</label>
		<input type="text" id="name" name="name" required>
	</div>
	<div class="field__email">
		<label for="email">Email</label>
		<input type="text" id="email" name="email" required>
	</div>

	<!-- Gonna be "step_two" -->
	<div class="field__password">
		<label for="password">Password</label>
		<input type="password" id="password" name="password" required>
	</div>
	<div class="field__password_confirm">
		<label for="password_confirm">Confirm password</label>
		<input type="password" id="password_confirm" name="password_confirm" required>
	</div>

	<!-- Gonna be "step_three" -->
	<div class="field__genre">
		<label for="genre">Select your gender</label>
		<select id="genre" name="genre" required>
			<option value="" disabled selected>Select...</option>
			<option value="1">Male</option>
			<option value="2">Female</option>
			<option value="3">Other</option>
		</select>
	</div>
	<button type="submit">Send</button>
</form>
const wizard = new Zangdar('#my_form')
const template = {
 'step_one': ['.field__name', '.field__email'],
 'step_two': ['.field__password', '.field__password_confirm'],
 'step_three': ['.field__genre']
}

wizard.createFromTemplate(template)

The generated wizard HTML markup will be :

<form id="my_form">
	<section data-label="step_one">
		<div class="field__name">
			<label for="name">Name</label>
			<input type="text" id="name" name="name" required>
		</div>
		<div class="field__email">
			<label for="email">Email</label>
			<input type="text" id="email" name="email" required>
		</div>
		<button data-next>Next</button>
	</section>

	<section data-label="step_two">
		<div class="field__password">
			<label for="password">Password</label>
			<input type="password" id="password" name="password" required>
		</div>
		<div class="field__password_confirm">
			<label for="password_confirm">Confirm password</label>
			<input type="password" id="password_confirm" name="password_confirm" required>
		</div>
		<button data-prev>Prev</button>
		<button data-next>Next</button>
	</section>

	<section data-label="step_three">
		<div class="field__genre">
			<label for="genre">Select your gender</label>
			<select id="genre" name="genre" required>
				<option value="" disabled selected>Select...</option>
				<option value="1">Male</option>
				<option value="2">Female</option>
				<option value="3">Other</option>
			</select>
		</div>
		<button type="submit">Send</button>
	</section>
</form>

  • getBreadcrumb(): Object

Returns an object representing the wizard breadcrumb with the label property as key, and the WizardStep as value.

const breadcrumb = Zangdar.getBreadcrumb()



TODO

  • Add WizardStep Available methods, getters and setters readme section
  • Update gh-pages API docs
  • Fix last step non functional custom validation