JQuery Validation

From Web Developer Network Wiki
Jump to: navigation, search

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:

  • className (string): The CSS Class to trigger this validator
  • error (string): The messages to display is test fails
  • test (function|object): A function that takes the element's value and a jQuery object containing the element, OR, An object specifying one or more of the built-in validators (see below).
  • options (object): [IGNORED IF test IS AN OBJECT] An object specifying one or more of the built-in validators (see below)


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)
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox