npm promotes metadefinitions
    Wondering what’s next for npm?Check out our public roadmap! »

    zangdar

    1.3.4 • Public • Published

    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

    • Finish Zangdar Available methods, getters and setters readme section
    • Add WizardStep Available methods, getters and setters readme section
    • Update gh-pages API docs

    Install

    npm i zangdar

    DownloadsWeekly Downloads

    52

    Version

    1.3.4

    License

    MIT

    Unpacked Size

    1.92 MB

    Total Files

    57

    Last publish

    Collaborators

    • avatar