jQuery.wizard

$( "form" ).wizard( [ options ] );

This plugin turns a standard HTML form into a wizard by breaking it into a series of well-defined steps. The purpose of these steps is to better group related inputs, preventing the user from becoming overwhelmed at the size or complexity of a form and helping them to better understand the structure of an unfamiliar form.

Structure

The basic stucture of the wizard revolves around steps and branches, the latter being optional. A simple, linear form may only require one branch that contains all of the steps, whereas a complex form may require the use of several branches, or even nested branches. The number of steps and branches in a form is thus left entirely to the developer.

Navigation

The wizard employs an asynchronous finite-state machine that determines how to navigate through itself. This is accomplished by defining states within the wizard, which are attached to steps, along with their corresponding action. Steps without states attached will perform the default action of going to the next step in the current branch.

States

<div class="step" data-state="state">

States are attached to steps via the state attribute, as defined by options.stateAttribute. States can refer to the name of a transition function, the index of a step or the name of the branch.

Transitions

$( "form" ).wizard({
    transitions: {
        gender: function( state, action ) {
            return state.step.find( "[name=gender]" ).val();
        }
    }
});

Transitions act as a bridge between one state and another. They can be used to allow custom logic to determine where to go next and should ultimately return a step index or branch name in the wizard.

Arguments

Transitions are called with the wizard object as the context and these arguments:

• state Object
  The current state of the wizard.

• action Function
  The action function should be used to pass the result back to the wizard in the case that your transition function is asynchronous.

Options

Options is a map of key/value pairs that can be passed into the plugin as the first argument upon initialization. The default values are shown below:

options: {
	animations: {
		show: {
			options: {
				duration: 0
			},
			properties: {
				opacity: "show"
			}
		},
		hide: {
			options: {
				duration: 0
			},
			properties: {
				opacity: "hide"
			}
		}
	},
	backward: ".backward",
	branches: ".branch",
	disabled: false,
	enableSubmit: false,
	forward: ".forward",
	header: ":header:first",
	initialStep: 0,
	stateAttribute: "data-state",
	stepClasses: {
		current: "current",
		exclude: "exclude",
		stop: "stop",
		submit: "submit",
		unidirectional: "unidirectional"
	},
	steps: ".step",
	submit: ":submit",
	transitions: {},
	unidirectional: false,

	/* callbacks */
	afterBackward: null,
	afterDestroy: null,
	afterForward: null,
	afterSelect: null,
	beforeBackward: null,
	beforeDestroy: null,
	beforeForward: null,
	beforeSelect: null,
	create: null
}

By default the wizard will start on the first step, show and hide steps instantly, transition to the next step in the same branch as the current step if no state attribute is present and allow movement forwards and backwards.

• animations Object
  Used to define custom transition animations on step changes. For more information, read up on jQuery's .animate() function.

  • show Object
    The options and properties that will be used when showing a step.

  • hide Object
    The options and properties that will be used when hiding a step.

• backward String
  A selector string used to indicate which elements to bind the backward() method to. The method will be triggered on click.

• branches String
  A selector string used to indicate which elements are branches within the wizard.

• enableSubmit Boolean
  Whether or not to enable the submit button on all steps.

• forward String
  A selector string used to indicate which elements to bind the forward() method to. The method will be triggered on click.

• header String
  A selector string used to locate the header of the wizard.

• initialStep String, Number, Array
  Which step to display after the wizard initializes. Accepts a string representing a step or branch ID, a number representing a step index, a jQuery object or DOM element representing a step or branch, or an array of arguments to be passed to the select() method.

• stateAttribute String
  The attribute, applied to steps, that contains the name of a state.

• stepClasses Object
  A map of meaningful step classes. These classes will have an effect on step behavior such as enabling or disabling navigation or preventing the step from being included in overall progress.

  • current String
    The class to toggle on the currently selected step.

  • exclude String
    If this class is present on a step the step will not be included in the progress estimate. This is useful for steps that might contain explanitory or introductory text without any inputs.

  • stop String
    If this class is present on a step the forward button will be disabled.

  • submit String
    If this class is present on a step the submit button will be enabled.

  • unidirectional String
    If this class is present on a step the backward button will be disabled.

• steps String
  A selector string used to indicate which elements are steps within the wizard.

• transitions Object
  A map of keys representing states and their corresponding action methods.

  • default Function
    The default transition to use on steps that contain no state attribute.

• unidirectional Boolean
  Whether or not this wizard should be unidirectional; that is allowing only forward movement.

Events

$( "form" )
    // Bind on initialization
    .wizard({
        eventHandler: function( event, state ) { ... }
    })
    // Bind at any other time
    .bind( "wizardeventhandler", function( event, state ) { ... });

Event handlers may be passed in on intialization in the options object, or they can be bound to the wizard at any time using the format wizardeventname (note that it must be in all lowercase).

• afterBackward or wizardafterbackward
  Triggered after the wizard has completed going backwards.

• afterDestroy or wizardafterdestroy
  Triggered after the wizard has been destroyed.

• afterForward or wizardafterforward
  Triggered after the wizard has completed going forwards.

• afterSelect or wizardafterselect
  Triggered after the wizard has completed selecting a new step.

• beforeBackward or wizardbeforebackward
  Triggered before the wizard attempts to move backwards. Returning false inside of this method will prevent the move.

• beforeDestroy or wizardbeforedestroy
  Triggered before the wizard is destroyed. Returning false inside of this method will prevent the destruction of the wizard.

• beforeForward or wizardbeforeforward
  Triggered before the wizard attempts to move forward. Returning false inside of this method will prevent the move.

• beforeSelect or wizardbeforeselect
  Triggered before the wizard attempts to move in any direction. Returning false inside of this method will prevent the move.

Arguments

Events are called with the wizard element as the context and these arguments:

• event Object
  The jQuery.Event object.

• state Object
  An object containing either the current state of the wizard (for after events) or the state the wizard will be updating to (for before events). See the state section for further information.

• [ update ] Function This function is available on any of the before events to allow deferred cancellation of events if asynchronous processing is needed.

Methods

$( "form" ).wizard( "methodName" [, args ] );

The wizard comes with plenty of public methods to help you navigate and get at any relevent information you may need.

• backward( [ event, howMany ] ) returns jQuery
  Step backward through the wizard.

  • event Event
    The jQuery.Event object. Used when the function is called via a trigger or event handler.

  • howMany Number
    How many steps to take backwards. Should be a positive integer greater than zero.

• branch( [ branch ] ) returns jQuery
  Returns a branch from the wizard. If no arguments are provided, it will return the currently active branch.

  • branch String
    The ID of a branch in the wizard.

• branches( [ branch ] ) returns jQuery
  Returns several branches in the wizard. If no arguments are provided, it will return all of the branches in the wizard.

  • branch String
    The ID of a branch in the wizard. If provided, all of the branches within the given branch are returned.

• branchesActivated() returns jQuery
  Returns all of the activated branches in the wizard. An activated branch is defined as any branch containing a step that has been visited.

• destroy() returns jQuery
  Completely remove the wizard functionality from the element it was attached to. This basically reverts the element to the state it was before the wizard was applied to it.

• form() returns jQuery
  Returns the form associated with the wizard.

• forward( [ event, howMany ] ) returns jQuery
  Step forward through the wizard.

  • event Event
    The jQuery.Event object. Used when the function is called via a trigger or event handler.

  • howMany Number
    How many steps to take forwards. Should be a positive integer greater than zero.

• isValidStep( step ) returns Boolean
  Returns whether or not a step is valid, or contained within the wizard.

  • step String, Number, jQuery, Element
    The step to check for in the wizard. Can be an element ID, step index, jQuery object or DOM element.

• isValidStepIndex( stepIndex ) returns Boolean
  Returns whether or not a step index is valid, or contained within the wizard.

  • stepIndex Number
    An integer representing the index of a step in the wizard.

• select( [ event, ] step [, branch, relative, history ] ) returns jQuery
  Selects a step within the wizard.

  • event Event
    The jQuery.Event object. Used when the function is called via a trigger or event handler.

  • step String, Number, jQuery, Element
    A step in the wizard. Can be an element ID, step index, jQuery object or DOM element.

  • branch String
    The ID of the branch that contains the step. Useful of searching for a step by step index relative to a branch. This parameter may be omitted even if further arguments are needed.

  • relative Boolean
    If true, the step argument becomes an integer representing the number of steps to move forwards or backwards relative to the current step. This parameter may be omitted even if further arguments are needed.

  • history Boolean, Array
    Whether or not to track the movements between the current step and the destination step. If set to false, the history will not be kept. This means that when hitting the back button on the selected step, the user will be taken directly back to the step they were on beforehand instead of visiting any steps in between. You can specify which steps will be included in the history yourself by passing an array of step indexes that will override whatever steps the plugin actually takes.

• state( [ step, branch, stepsTaken ] ) returns Object
  Returns an object containing the state of the wizard at a certain step, or null if the step could not be found. If no arguments are provided, returns the current state of the wizard. See the state section for further information.

  • step String, Number, jQuery, Element
    A step in the wizard. Can be an element ID, step index, jQuery object or DOM element.

  • branch String
    The ID of the branch that contains the step. Useful of searching for a step by step index relative to a branch. This parameter may be omitted even if further arguments are needed.

  • stepsTaken Array
    An array of step indexes that represent the path taken to get to the given step from the current step. This should be provided if tracking history for the generation of an accurate state.

• step( [ step, branch ] ) returns jQuery
  Returns a step from the wizard. If no arguments are provided, it will return the currently selected step in the wizard.

  • step String, Number, jQuery, Element
    A step in the wizard. Can be an element ID, step index, jQuery object or DOM element.

  • branch String
    The ID of the branch that contains the step. Useful of searching for a step by step index relative to a branch. This parameter may be omitted even if further arguments are needed.

• stepCount() returns Number
  Returns the number of steps in the wizard.

• stepIndex( [ step, branch, relative ] ) returns Number
  Returns the index of a step in the wizard, or -1 of the step could not be found. If no arguments are provided, it will return the index of the currently selected step in the wizard.

  • branch String
    The ID of the branch that contains the step. Useful of searching for a step by step index relative to a branch. This parameter may be omitted even if further arguments are needed.

  • relative Boolean
    If true, the index returned will be relative to its containing branch.

• steps( [ branch ] ) returns jQuery
  Returns steps within the wizard. If no arguments are provided, it will return all of the steps in the wizard.

  • branch String
    An ID of a branch within the wizard. If this parameter is given, all of the steps within the branch will be returned.

• stepsActivated() returns jQuery
  Returns all of the activated steps in the wizard. An activated step is defined as one that the user has visited.

• submit() returns jQuery
  Submits the form attached to the wizard.

State

{
    branch: [ form#defaultBranch.ui-wizard-form ],
    branchLabel: "defaultBranch",
    branchStepCount: 3,
    branchesActivated: [ "defaultBranch" ],
    isFirstStep: true,
    isFirstStepInBranch: true,
    isLastStep: false,
    isLastStepInBranch: false,
    isMovingForward: false,
    percentComplete: 0,
    step: [ div.step ],
    stepIndex: 0,
    stepIndexInBranch: 0,
    stepsActivated: [ 0 ],
    stepsComplete: 0,
    stepsPossible: 2,
    stepsRemaining: 2
}

The wizard keeps track of its current state using an object map of keys and values. This map can be accessed at any time via the state() method. It is also passed in as the second argument to event handlers. The keys and their values are outlined below.

• branch jQuery
  The branch the wizard is currently on.

• branchLabel String
  The label, or ID, of the currently active branch.

• branchStepCount Number
  The total number of steps in the current branch.

• branchesActivated Array
  An array containing all of the currently activated branch labels.

• isFirstStep Boolean
  Whether or not the current step is the first step in the wizard.

• isFirstStepInBranch Boolean
  Whether or not the current step is the first step in its containing branch.

• isLastStep Boolean
  Whether or not the current step is the last step in the wizard.

• isLastStepInBranch Boolean
  Whether or not the current step is the last step in its containing branch.

• isMovingForward Boolean
  Whether or not the wizard is progressing forward, that is that the current step index is greater than the previous step index.

• percentComplete Number
  A number representing the estimated percent of completion of the wizard. This is a numerical value between 0 and 100.

• step jQuery
  The step the wizard is currently on.

• stepIndex Number
  The index of the currently active step.

• stepIndexInBranch Number
  The index of the currently active step relative to its containing branch.

• stepsActivated Array
  An array containing all of the currently activated step indexes.

• stepsComplete Number
  The number of steps in the wizard that the user has completed. These steps will be contained in the stepsActivated array, minus any steps the developer has decided to exclude.

• stepsPossible Number
  The estimated number of steps the user could possibly activate. This is calculated by counting all of the steps in every branch the user has activated, minus any steps the developer has decided to exclude.

• stepsRemaining Number
  The estimated difference between stepsComplete and stepsPossible.

Installation

The easiest way to install is via NPM:

npm install @kflorence/jquery-wizard

Or Bower:

bower install jquery-wizard

You can also download releases directly from github. The latest uncompressed version is available here:

• jquery.wizard.js

Requirements

• jQuery
  Versions 1.7.0 or higher.

• jQuery UI
  Core and Widget, versions 1.9.0 or higher.

Compatibility

Tested and verified to work on the following browsers:

• Internet Explorer
  Versions 6.0 and higher.

• Mozilla Firefox
  Versions 3.0 and higher.

• Google Chrome
  Versions 7.0 and higher.

Found a bug? Submit an issue. Tested in another browser? Send me a message or fork this project and add the browser to this readme.

Integration

This plugin has been designed to integrate well with the following plugins:

• jQuery Form
  AJAX form submission capabilities.

• jQuery Validation
  Form input validation which can prevent step changing or submission.

• jQuery Autosave
  Automatic form submission based on user-defined criteria.

• jQuery Masked Input
  Ensures properly formatted form input data.

License

Copyright (c) 2017 Kyle Florence
Dual licensed under the MIT and GPLv2 licenses.