Skip to content

Latest commit

 

History

History
563 lines (421 loc) · 19.9 KB

readme.md

File metadata and controls

563 lines (421 loc) · 19.9 KB
Raw

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:

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:

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:

License

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