A jQuery UI Wizard Widget
Include the JS and CSS as you would expect:
<script src="jquery.jWizard.js"></script>
<link href="jquery.jWizard.css" rel="stylesheet">A wizard can be comprised of a <form>, but any other (block-level) element,
like <div> will also work.
<form id="wizard">
<!-- steps will go here -->
</form>
<!-- or -->
<div id="wizard">
<!-- steps will go here -->
</div>A step can also be made up of just about any (block-level) element as well.
<fieldset>, the <legend> element will contain the step's title.title or data-jwizard-title attribute to specify a titleFor example:
<fieldset>
<!-- step title -->
<legend>Step 1</legend>
<!-- step content -->
</fieldset>
<!-- or -->
<div title="Step 1">
<!-- step content -->
</div>
<!-- or -->
<div data-jwizard-title="Step 1">
<!-- step content -->
</div>Lastly, initialize the wizard via JS:
$("#wizard").jWizard();What you will see here is a what you get with no configuration options set during the initialization. See the available options below to learn how to configure.
Boolean (Default: true)Determines whether or not to include a title bar in the interface.
Boolean (Default: true)Determines whether or not to include a navigation/menu bar
Each key of the buttons hash represents one of the 4 generated
buttons. These objects are passed directly to jQuery, giving you
a lot of control over the resulting HTML by simply changing the
properties of the default configuration object. (setting an entire
button object here as false or null will cause that button to
not be rendered at all)
The icons parameter is an exception, that value is extracted
before generating the button HTML and is handed off to the jQuery
UI Button Widget initialization.
The cancel button is generated as a reset button, with an the
ui-priority-secondary class for de-emphasis. It is also
aligned furthest to the left.
{
"class": "ui-priority-secondary",
text: "Cancel",
type: "reset",
icons: {
primary: "ui-icon-circle-close"
}
}The previous button is generated as a standard button, it is aligned to the left (but right of the cancel button)
{
text: "Previous",
type: "button",
icons: {
primary: "ui-icon-circle-triangle-w"
}
}The next button is generated as a standard button, it is aligned to the right.
{
text: "Next",
type: "button",
icons: {
primary: "ui-icon-circle-triangle-e"
}
}The finish button is generated as a submit button, with both
ui-priority-primary and ui-state-highlight classes for maximum
emphasis. It is also aligned to the right.
{
"class": "ui-priority-primary ui-state-highlight",
text: "Finish",
type: "submit",
icons: {
secondary: "ui-icon-circle-check"
}
}These options configure the extended progressbar. (formerly known as the counter)
By setting this value to false or null, the progressbar will be
ignored altogether.
These options configure various transitions and effects used by jWizard. As of this writing, (v2.0) the only transitions applied are to the show and hide of steps. See the jQuery UI documentation for complete documentation on the available options.
effects: {
steps: {
hide: {
effect: "blind",
direction: "left",
duration: 250
},
show: {
effect: "blind",
direction: "left",
duration: 250
}
}
}These events are triggered on the root element for the wizard itself. As such, they can be bound to as part of the configuration options of the wizard widget.
The internal widgetEventPrefix is set as wizard (not jWizard) so
remember that when binding to the cancel and finish events after
the initialization.
Triggered when the user clicks the cancel button. If the button is also
acting as a reset button (which is the default behavior) you can return
false here to cancel the form reset. (or simply change the button type
in the config)
Triggered when the user clicks the finish button. If the button is also
acting as a submit button (which is the default behavior) you can return
false here to cancel the form submission.
These events are triggered on the step elements directly, and while they will bubble up to the wizard widget, the typical pattern is to bind directly to the step elements.
Triggered before a step is hidden. (which occurs when transitioning from one step to another) By cancelling this event, the transition will not be completed, leaving this step active.
This event is expected to be used to validate form inputs, and to cancel the event when invalid data is found.
Triggered after a step has been hidden, and before the next step is to be shown. It cannot be cancelled.
Triggered before a step is to be shown, and after the previous step has been hidden. Cancelling this event will revert the wizard back to the previous step.
This event is expected to be used to initialize the interface for the upcoming step.
Triggered after a step has been shown. It cannot be cancelled.
This event is expected to be used to refresh/reposition interface elements that may not be able to be positioned correctly when the elements are still hidden in the DOM.
As of v2.0, jWizard comes bundled with a widget that extends the
jQuery UI Progressbar Widget widget.
This extension unobtrusively adds a new feature, a label reflecting the
value (in relation to max) that is positioned over the progressbar itself.
This feature is "opt-in" only. (by setting the label option)
That being said, if you have included jWizard, you have access to the enhanced progressbar without any additional work on your part. The eventual goal is to submit this feature to the jQuery UI team for inclusion.
These options are in addition to the documented options of the jQuery UI Progressbar Widget
String (Default: null)This option has 2 possible values, each adds a label to the progressbar:
"count" adds a label that is formatted as "55 of 100""percentage" adds a label that is formatted as "55%"String (Default: null)This option specifies a "suffix" for the label, and appends the specified string to the generated label text.
For example, jWizard appends "Complete" by default so the label would appear
as "3 of 5 Complete".
The default configuration includes quite a lot, so feel free to switch things off once you realize you don't need them.
Each button has a configuration hash that has full control over the generated HTML. (see main docs)
To remove the progressbar from the wizard,
simply use false as the config option
There are 2 main options for the progressbar:
label and append (see progressbar documentation)
Each button has a configuration hash that has full control over the generated HTML. (see main docs)
| Version | Date | Comments |
|---|---|---|
| v2.0.1 | September 22, 2013 |
|
| v2.0.0 | March 4, 2013 |
|
| Past versions are not recorded as v2 is a complete rewrite anyways, plus I never really kept a detailed change log anyways, sorry :( | ||
Make feature requests of your own on the Github Issues Page
For anyone who wants to hack on jWizard (would be much appreciated) with me, you should be able to get started pretty easily.
Install node.js, (v0.8+) then install the dependencies:
npm installYou'll need an internet connection to run the tests, this is because the jQuery and jQuery UI scripts are loaded via the Google CDN dynamically. In addition, the version of each of those dependencies can be changed on the fly as well to run the suite against various version combinations.
make testTo run tests against a specific version combination of jQuery and jQuery UI, which can be specified via the command line:
make test JQUERY=1.8.3 JQUERYUI=1.8.24will run the test suite against jQuery 1.8.3 and jQuery UI 1.8.24.
Submit your patches as Github Pull Requests. Please modify the tests to reflect your changes, and make sure they all pass before submitting your PR. Also, there is no formal style guide, just follow the conventions that are in place.