Overview
Provides an implemenation of a UI wizard built on jQuery and Bootstrap. It takes care of the plumbing for moving back and forth between steps, validation, hooks for key events, etc.
Dependencies
The project was built on the following. It does nothing fancy and will probably work with all future versions:
- jQuery 2.2.4
- Bootstrap 3.3.6
Setup
The use bootstrap-wizard in your project, include the following:
- wizard.css
- wizard.min.js
Markup
The wizard depends on structured HTML to define the wizard and the steps for it. The order of the steps presented is defined by the order of the divs within the wizard. The wizard itself is defined by the wizard class and each step is defined by the wizard-step class.
Options
Automatic initialization based on css class is not supported. Chances are that every wizard will need to supply some initialization options. To initialize a wizard, use JavaScript passing the options. The following are the default options:
| Name | Default | Description |
| title | Empty | Displayed as the title of the wizard. This title can be overridden by step titles if the step has the data-title attribute. |
| validators | null | An array of objects used to validate steps. Each object is {step:1, validation: function(){}}. See Custom Validation. |
| onSubmit | null | A function called when the Submit button is clicked |
| onReset | null | A function called when the wizard is closed or completed. The purpose of this event is to reset all elements in the wizard. |
| onCancel | null | A function called when the wizard is canceled. This happens when the Cancel button is clicked, the "X" button in the header is clicked or the Escape key is pressed. |
| onClose | null | A function called when the wizard is closed |
| onOpen | null | A function called when the wizard is opened |
| previousText | << Back | The text of the Previous button |
| nextText | Next >> | The text of the Next button |
| submitText | Submit | The text of the Submit button |
| cancelText | Cancel | The text of the Cancel button |
| showCancel | true | A boolean controlling if the Cancel button is shown. If true, the Cancel button will be displayed, the "X" button will be in the title and the Escape key will cancel the wizard. |
| showPrevious | true | A boolean controlling if the Previous button is shown |
| showProgress | false | A boolean controlling if a progress bar is shown. If the wizard contains numerous steps, it may be friendly to display a progress bar to the user. This uses the bootstrap progress bar. |
| isModal | true | A boolean controlling if the wizard is presented as a bootstrap dialog. If false then the wizard will be presented precisely where it lives in the DOM. |
| autoOpen | false | A boolean controlling if the wizard is automatically opened when it is initialized. Typically this is only true when isModal is false. |
Methods
The wizard is implemented as a jQuery plugin, so methods are called as such:
The following methods are available for a wizard instance:
| Name | Arguments | Description |
| open | n/a | Opens the wizard on step one. This raises the onOpen event. |
| close | n/a | Closes the wizard. This raises the onReset, onClose events. |
| info | text | Displays the text with an alert-info css class |
| warning | text | Displays the text with an alert-warning css class |
| submit | n/a | Initates the submit sequence as if the last step is completed and there are no validation errors. |
| success | text | Displays the text with an alert-success css class |
| error | text | Displays the text with an alert-danger css class |
| end | options | This method is meant to be called at the end of the onSubmit event. The options is an object: {info:'', warning:'', success:'', error:'', autoClose:true/false/integer} The info/warning/success/error will control the messages displayed. The autoClose controls if the wizard is automatically closed. If false, it is not closed. If true, it is closed after two seconds. If an integer is specified, it will close after that number of milliseconds. |
Validation
Each step of a wizard can be validated before moving onto the next step. There are two mechanisms for validation:
- Form validation
- Custom validation
Form Validation
If the step contains a form element, the wizard will attempt to validate it. There are numerous plugins out there for form validation. The wizard is not dependent on any specific implementation. It will attempt to call a valid method and a validate method on the form object if they exist. If either method exists and returns false, the wizard will not advance to the next step. The wizard assumes the validation implementation takes care of updating the UI with errors.
Custom Validation
You can supply your own custom validation through the validators option. This takes an array of objects. The first property (step) is a 1-based index of the step it belongs to. The second property (validate) is a function that will be called when Next is clicked on that step. If it is the last step, it will be called when Submit is clicked.
The wizard looks for a return value of false from the validate function. Any other value is assumed to mean success and the wizard will move onto the next step. If the wizard receives false, it will remain on the current step. The custom validator is responsible to provide feedback to the user if there are validation errors. In the example below, the validator is writing the error to the wizard UI via the error method.
Examples
Simple shows the basic setup
Events shows all event hooks
No Modal shows the wizard without using modal dialogs
Kitchen Sink shows just about everything you can do with the wizard