Formwizard Reference
FormWizard is a class that mutates a form into a wizard. Once it is applied to its target, the user will be presented with a series of pages making the process of fill a complex form easiest.
In the form, the different pages are defined by grouping the controls and the widgets they need into a fieldset or similar container.
FormWizard doesn't make any assumption on business rules or presentation1. It limit itself to manage the page switch, providing appropiate hooks, and inject, if required to do so, a container with the controls needed to move from a step to the next one.
Syntax
new FormWizard(target [, options] [, flow]);
Arguments
- target
- (mixed, mandatory) the DOM Element (or its id) to be enhanced by FormWizard
- options
- (object, optional) a key/value set of options
- flow
- (object, optional) a key/value set of bindings
Target
The only mandatory parameter, it can be a Mootools augmented object, a DOM one or a string representing the id of the wizard.
Options
- formClass (default "wizard") is the class appended to the wizard container (useful for styling)
- pageClass (default "wizard-page") is the class the plugin uses to identify the wizard pages
- defaultButtonClass (default "wizard-button") is the class appended to the buttons used to change wizard pages (useful for styling)
- controlAreaClass (default "wizard-control-area") is the class appended to the area containing the wizard buttons
- firstPage (default 1) is the first page to show to the user.
- enterLastPage (default null) is the function called from the wizard before entering the last page, useful to quickly personalize the wizard behaviour without resorting to the FlowControl options. It overwrite the corresponding FlowControl behaviour if both are present.
- createControlArea (default: false) if true create a div with the needed control buttons and inject it at the form bottom.
- showControlCaptions (default: true) if false omits (even if specified) the caption (title) of the control buttons.
- wizardControls (default ["reset", "backward", "forward"]) is an array listing the desired buttons (to be created or already in place), the order matters if createControlArea is true. Recognized buttons are reset, backward, forward and submit, use should be clear.
- controls is an object containing configuration directives. It is aimed to configure the aspect of the various wizard buttons. It has four properties: submit, forward, backward and reset.
- currentPageClassPrefix is the prefix to be used for marking the wizard container with a class describing the page displayed in order to give a css hook to fulfill dedicated (presentation?) tasks when the wizard flow reach specific pages. An example can be hide and display the control buttons with css rules.
Flow
The third parameter should be a set of bindings to single pages of the wizard. The key have to correspond to the id of the page to script and the value is an object addressing functions used by the wizard to evaluate the opportunity to switch form a page to the next one. Formwizard only knows about two keys: onEnter and onExit. Other keys will be disregarded.
When not overloaded the page inherits an object like this:
{ "onEnter": $lambda(true), "onExit": $lambda(true) }
Note
1 In the package there is a simple css, and others are planned