JQuery Validation
This jQuery plugin allows you to attach validation to HTML forms. As the user fills out the form inputs or when the form is submitted, error messages can be displayed to assist the user in providing acceptable values.
To attach validation to individual form elements, you add CSS classes to the element's HTML markup. The following example shows an element that would validate a required value.
<input type="text" name="foobar" class="required-entry" />
To initialize any form you wish to have validation for, use the plugin's initializing method described below. For example, if you have a form with an ID of my_form, the script to start validation for it might look like:
<script type="text/javascript">
WDN.initializePlugin('form_validation', [function() {
$('#my_form').validation();
}]);
</script>
When displaying a validation error message for an element, the messages are appended to the closest element with the CSS class advice-container, otherwise the element's container is used (see containerClassName in options).
If the advice-container is used the CSS classes validation-passed/validation-failed will be added to it, otherwise the individual elements will have the CSS classes added. See addClassNameToContainer option for more CSS classes that can be added on to the container.
Contents |
Plugin Methods
| Method | Description |
|---|---|
validation(options)
|
Sets up a form to check and display validation messages. |
Plugin Options
| Option Name | Option Type | Default Value | Description |
|---|---|---|---|
onSubmit
|
(boolean) | true
|
Should validation be checked on form submit |
stopOnFirst
|
(boolean) | false
|
Should the validation process stop at the first error |
immediate
|
(boolean) | false
|
Should validation occur when a field changes |
focusOnError
|
(boolean) | true
|
Should the first invalid element be focused |
useTitles
|
(boolean) | false
|
Should the element's title attribute be used to override the validation error message |
addClassNameToContainer
|
(boolean) | false
|
Should the validation-passed/validation-error CSS classes be added to the element's container
|
containerClassName
|
(string: CSS Class) | 'input-box'
|
The CSS class of container for each element. If a matching element is not found within the parents of the element, the first parent will be used. |
Events
You can attach custom handlers to the form or individual element to make callbacks after validation occurs.
| Event Name | Description |
|---|---|
validate-element
|
This event is triggered after an element has been tested with a Validation method. The handler is passed the event (object) and the test result (boolean) as parameters. |
validate-form
|
This event is triggered after the form has completed validation. The handler is passed the event (object) and the validation result (boolean) as parameters. |
Example Bindings
$('#my_custom_element').bind('validate-element', function(event, result) { ... });
$('#my_form').bind('validate-form', function(event, result) { ... });
Utilities
| Method | Description |
|---|---|
jQuery.validation.addMethod(className, error, test, options)
|
Adds a CSS class Validation method for all validators to use Parameters:
|
Example Custom Validation Method
WDN.jQuery.validation.addMethod('validate-confirm-email',
'This value must match the value of the email field.',
{equalToField:'#email_field'});
Included Methods/CSS Classes
| Method CSS Class | Description |
|---|---|
IsEmpty
|
Requires an empty value (trimmed, used by other methods that aren't required) |
required-entry
|
Requires an non-empty value (trimmed) |
validate-number
|
Checks for a formatted number |
validate-digits
|
Checks for a value with only numbers |
validate-alpha
|
Checks for a value with only letters |
validate-code
|
Checks for a value that begins with a letter and only contains letters numbers or underscore(_) |
validate-alphanum
|
Checks for a value with only letters and numbers |
validate-phoneStrict
|
Checks for a phone number using a strict US format |
validate-phoneLax
|
Checks for a phone number using a relaxed format |
validate-date
|
Checks for a javascript parseable date |
validate-email
|
Check for an email address |
validate-url
|
Checks for a URL prefix |
validate-zip
|
Checks for a US zip or zip+4 |
validate-currency-dollar
|
Checks for a formatted dollar amount. Ex: $100.40 |
validate-one-required
|
Requires a non-empty input within the parent of the element |
validate-one-required-by-name
|
Requires a checked checkbox/radio button with the element's name |
validate-unsigned-number
|
Checks for a formatted number > 0 |
validate-greater-than-zero
|
Checks for a number > 0 |
validate-zero-or-greater
|
Checks for a number >= 0 |
validate-percents
|
Requires a number between 0 and 100 |
Built-in Validators
Each of these are object keys that can be passed a value to validate with. For example to check if the element's value is one of the values of an array, the definition would be {oneOf:[1,2,3]}
| Object Key | Object Value | Description |
|---|---|---|
pattern
|
(regular expression) | Tests if the elements value passes the provided regular expression. |
minLength
|
(number) | Checks the "string" length of the value |
maxLength
|
(number) | Checks the "string" length of the value |
min
|
(number) | Checks the numeric value of element |
max
|
(number) | Checks the numeric value of element |
notOneOf
|
(array) | Checks if the value is in the array |
oneOf
|
(array) | Checks if the value is in the array |
is
|
(string) | Checks if the value is equal to the string |
isNot
|
(string) | Checks if the value is not equal to the string |
equalToField
|
(string: CSS Selector) | Checks if the value equals the value of the element defined by the provided CSS Selector |
notEqualToField
|
(string: CSS Selector) | Checks if the value equals the value of the element defined by the provided CSS Selector |
include
|
(array of Validation CSS Classes) | Checks if the value passes all of the CSS Class Validation methods (provides a way to group existing Validation methods) |
