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 thebackward()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 theforward()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 theselect()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.
- default Function
-
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.
- branch String
-
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.
- branch String
-
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.
- step String, Number, jQuery, 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.
- stepIndex Number
-
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.
- branch String
-
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:
Requirements
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.