|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Documentation |
| 4 | +--- |
| 5 | + |
| 6 | +# Validate forms like you've never validated before! |
| 7 | + |
| 8 | +**"But doesn't jQuery make it easy to write your own validation plugin?"** |
| 9 | +Sure, but there are still a lot of subtleties to take care of: You need a standard library of validation methods (such as emails, URLs, credit card numbers). You need to place error messages in the DOM and show and hide them when appropriate. You want to react to more than just a submit event, like keyup and blur. |
| 10 | +You may need different ways to specify validation rules according to the server-side enviroment you are using on different projects. And after all, you don't want to reinvent the wheel, do you? |
| 11 | + |
| 12 | +**"But aren't there already a ton of validation plugins out there?"** |
| 13 | +Right, there are a lot of non-jQuery-based solutions (which you'd avoid since you found jQuery) and some jQuery-based solutions. This particular one is one of the oldest jQuery plugins (started in July 2006) and has proved itself in projects all around the world. There is also an [article](http://bassistance.de/2007/07/04/about-client-side-form-validation-and-frameworks/) discussing how this plugin fits the bill of the should-be validation solution. |
| 14 | + |
| 15 | +Not convinced? [Have a look at this example](https://jqueryvalidation.org/files/demo/): |
| 16 | + |
| 17 | +<pre><code> |
| 18 | +<form class="cmxform" id="commentForm" method="get" action=""> |
| 19 | + <fieldset> |
| 20 | + <legend>Please provide your name, email address (won't be published) and a comment</legend> |
| 21 | + <p> |
| 22 | + <label for="cname">Name (required, at least 2 characters)</label> |
| 23 | + <input id="cname" name="name" minlength="2" type="text" required> |
| 24 | + </p> |
| 25 | + <p> |
| 26 | + <label for="cemail">E-Mail (required)</label> |
| 27 | + <input id="cemail" type="email" name="email" required> |
| 28 | + </p> |
| 29 | + <p> |
| 30 | + <label for="curl">URL (optional)</label> |
| 31 | + <input id="curl" type="url" name="url"> |
| 32 | + </p> |
| 33 | + <p> |
| 34 | + <label for="ccomment">Your comment (required)</label> |
| 35 | + <textarea id="ccomment" name="comment" required></textarea> |
| 36 | + </p> |
| 37 | + <p> |
| 38 | + <input class="submit" type="submit" value="Submit"> |
| 39 | + </p> |
| 40 | + </fieldset> |
| 41 | +</form> |
| 42 | +<script> |
| 43 | +$("#commentForm").validate(); |
| 44 | +</script> |
| 45 | +</code></pre> |
| 46 | + |
| 47 | +### Isn't that nice and easy? |
| 48 | +A single line of jQuery to select the form and apply the validation plugin, plus a few annotations on each element to specify the validation rules. |
| 49 | + |
| 50 | +Of course that isn't the only way to specify rules. You also don't have to rely on those default messages, but they come in handy when starting to setup validation for a form. |
| 51 | + |
| 52 | +### A few things to look out for when playing around with the demo |
| 53 | + |
| 54 | +* After trying to submit an invalid form, the first invalid element is focused, allowing the user to correct the field. If another invalid field - that wasn't the first one - was focused before submit, that field is focused instead, allowing the user to start at the bottom if he or she prefers. |
| 55 | +* Before a field is marked as invalid, the validation is lazy: Before submitting the form for the first time, the user can tab through fields without getting annoying messages - they won't get bugged before having the chance to actually enter a correct value |
| 56 | +* Once a field is marked invalid, it is eagerly validated: As soon as the user has entered the necessary value, the error message is removed |
| 57 | +* If the user enters something in a non-marked field, and tabs/clicks away from it (blur the field), it is validated - obviously the user had the intention to enter something, but failed to enter the correct value |
| 58 | + |
| 59 | +That behaviour can be irritating when clicking through demos of the validation plugin - it is designed for an unobtrusive user experience, annoying the user as little as possible with unnecessary error messages. So when you try out other demos, try to react like one of your users would, and see if the behaviour is better then. If not, please let me know about any ideas you may have for improvements! |
| 60 | + |
| 61 | +# API Documentation |
| 62 | + |
| 63 | +You're probably looking for |
| 64 | + |
| 65 | +### [Options for the validate() method](/validate) |
| 66 | + |
| 67 | +If not, read on. |
| 68 | + |
| 69 | +Throughout the documentation, two terms are used very often, so it's important that you know their meaning in the context of the validation plugin: |
| 70 | + |
| 71 | +* **method**: A validation method implements the logic to validate an element, like an email method that checks for the right format of a text input's value. A set of standard methods is available, and it is easy to write your own. |
| 72 | +* **rule**: A validation rule associates an element with a validation method, like "validate input with name "primary-mail" with methods "required" and "email". |
| 73 | + |
| 74 | +## Plugin methods |
| 75 | + |
| 76 | +This library adds three jQuery plugin methods, the main entry point being the `validate` method: |
| 77 | + |
| 78 | +* [`validate()` - Validates the selected form.](/validate) |
| 79 | +* [`valid()` - Checks whether the selected form or selected elements are valid.](/valid) |
| 80 | +* [`rules()` - Read, add and remove rules for an element.](/rules) |
| 81 | + |
| 82 | +## Custom selectors |
| 83 | + |
| 84 | +This library also extends jQuery with three custom selectors: |
| 85 | + |
| 86 | +* [`:blank` - Selects all elements with a blank value.](/blank-selector) |
| 87 | +* [`:filled` - Selects all elements with a filled value.](/filled-selector) |
| 88 | +* [`:unchecked` - Selects all elements that are unchecked.](/unchecked-selector) |
| 89 | + |
| 90 | +## Validator |
| 91 | + |
| 92 | +The validate method returns a Validator object that has a few public methods that you can use to trigger validation programmatically or change the contents of the form. The validator object has more methods, but only those documented here are intended for usage. |
| 93 | + |
| 94 | +* [`Validator.form()` - Validates the form.](/Validator.form) |
| 95 | +* [`Validator.element()` - Validates a single element.](/Validator.element) |
| 96 | +* [`Validator.resetForm()` - Resets the controlled form.](/Validator.resetForm) |
| 97 | +* [`Validator.showErrors()` - Show the specified messages.](/Validator.showErrors) |
| 98 | +* [`Validator.numberOfInvalids()` - Returns the number of invalid fields.](/Validator.numberOfInvalids) |
| 99 | +* [`Validator.destroy()` - Destroys this instance of validator.](/Validator.destroy) |
| 100 | + |
| 101 | +There are a few static methods on the validator object: |
| 102 | + |
| 103 | +* [`jQuery.validator.addMethod()` - Add a custom validation method.](/jQuery.validator.addMethod) |
| 104 | +* [`jQuery.validator.format()` - Replaces {n} placeholders with arguments.](/jQuery.validator.format) |
| 105 | +* [`jQuery.validator.setDefaults()` - Modify default settings for validation.](/jQuery.validator.setDefaults) |
| 106 | +* [`jQuery.validator.addClassRules()` - Add a compound class method.](/jQuery.validator.addClassRules) |
| 107 | + |
| 108 | +## List of built-in Validation methods |
| 109 | + |
| 110 | +A set of standard validation methods is provided: |
| 111 | + |
| 112 | +* [`required` - Makes the element required.](/required-method) |
| 113 | +* [`remote` - Requests a resource to check the element for validity.](/remote-method) |
| 114 | +* [`minlength` - Makes the element require a given minimum length.](/minlength-method) |
| 115 | +* [`maxlength` - Makes the element require a given maximum length.](/maxlength-method) |
| 116 | +* [`rangelength` - Makes the element require a given value range.](/rangelength-method) |
| 117 | +* [`min` - Makes the element require a given minimum.](/min-method) |
| 118 | +* [`max` - Makes the element require a given maximum.](/max-method) |
| 119 | +* [`range` - Makes the element require a given value range.](/range-method) |
| 120 | +* [`step` - Makes the element require a given step.](/step-method) |
| 121 | +* [`email` - Makes the element require a valid email](/email-method) |
| 122 | +* [`url` - Makes the element require a valid url](/url-method) |
| 123 | +* [`date` - Makes the element require a date.](/date-method) |
| 124 | +* [`dateISO` - Makes the element require an ISO date.](/dateISO-method) |
| 125 | +* [`number` - Makes the element require a decimal number.](/number-method) |
| 126 | +* [`digits` - Makes the element require digits only.](/digits-method) |
| 127 | +* [`equalTo` - Requires the element to be the same as another one](/equalTo-method) |
| 128 | + |
| 129 | +Some more methods are provided as add-ons, and are currently included in additional-methods.js in the download package. Not all of them are documented here: |
| 130 | + |
| 131 | +* [`accept` - Makes a file upload accept only specified mime-types.](/accept-method) |
| 132 | +* [`creditcard` - Makes the element require a credit card number.](/creditcard-method) |
| 133 | +* [`extension` - Makes the element require a certain file extension.](/extension-method) |
| 134 | +* [`phoneUS` - Validate for valid US phone number.](/phoneUS-method) |
| 135 | +* [`require_from_group` - Ensures a given number of fields in a group are complete.](/require_from_group-method) |
| 136 | + |
| 137 | +You can find the [source code for all additional methods in the GitHub repository](https://github.com/jzaefferer/jquery-validation/tree/master/src/additional). |
| 138 | + |
| 139 | +It is possible to re-define the implementation of the built-in rules using the [`$.validator.methods` property](/jQuery.validator.methods/) |
| 140 | + |
| 141 | +# [General Guidelines](/reference) |
| 142 | + |
| 143 | +The General Guidelines section provides detailed discussion of the design and ideas behind the plugin, explaining why certain things are as they are. It covers the features in more detail than the API documentation, which just briefly explains the various methods and options available. |
| 144 | + |
| 145 | +If you've decided to use the validation plugin in your application and want to get to know it better, it is recommended that you read the guidelines. |
| 146 | + |
| 147 | +## Fields with complex names (brackets, dots) |
| 148 | + |
| 149 | +When you have a name attribute like user[name], make sure to put the name in quotes. More details in the [General Guidelines](/reference). |
| 150 | + |
| 151 | +## Too much recursion |
| 152 | + |
| 153 | +Another common problem occurs with this code: |
| 154 | + |
| 155 | +<pre><code> |
| 156 | + $("#myform").validate({ |
| 157 | + submitHandler: function(form) { |
| 158 | + // some other code |
| 159 | + // maybe disabling submit button |
| 160 | + // then: |
| 161 | + $(form).submit(); |
| 162 | + } |
| 163 | + }); |
| 164 | +</code></pre> |
| 165 | + |
| 166 | +This results in a too-much-recursion error: <code>$(form).submit()</code> triggers another round of validation, resulting in another call to submitHandler, and voila, recursion. Replace that with form.submit(), which triggers the native submit event instead and not the validation. |
| 167 | + |
| 168 | +So the correct code looks slightly different: |
| 169 | + |
| 170 | +<pre><code> |
| 171 | + $("#myform").validate({ |
| 172 | + submitHandler: function(form) { |
| 173 | + form.submit(); |
| 174 | + } |
| 175 | + }); |
| 176 | +</code></pre> |
| 177 | + |
| 178 | +# Demos |
| 179 | + |
| 180 | +## [The Marketo sign-up form](https://jqueryvalidation.org/files/demo/marketo/) |
| 181 | +### [The Marketo sign-up form, step 2](https://jqueryvalidation.org/files/demo/marketo/step2.htm) |
| 182 | +Based on an old version of the marketo.com sign-up form. The custom validation was once replaced with this plugin. Thanks to Glen Lipka for contributing it! |
| 183 | + |
| 184 | +*Notable features of the demo:* |
| 185 | + |
| 186 | +* Customized message display: No messages displayed for the required method, only for typing-errors (like wrong email format); A summary is displayed at the top ("You missed 12 fields. They have been highlighted below.") |
| 187 | +* Remote validation of email field. Try to enter eg. glen@marketo.com |
| 188 | +* Integration with masked-input plugin, see Zip and Phone fields and Credit Card Number on step 2 |
| 189 | +* A custom method for making the billing address on step 2 optional when "Same as Company Address" is checked |
| 190 | +* A custom method for checking the password: Checks that the password contains at least one number and one character and that it is at least 6 characters long. If the user blurs the field with an invalid value, the input is emptied and gets focus again. |
| 191 | + |
| 192 | +## [The Remember The Milk sign-up form](https://jqueryvalidation.org/files/demo/milk/) |
| 193 | +The sign-up form from rememberthemilk.com (based on an older version). The custom validation was replaced using this plugin. Thanks to RTM for contributing! |
| 194 | + |
| 195 | +*Notable features of the demo:* |
| 196 | + |
| 197 | +* Custom message display, based on the original table layout, using success option to display a checkmark for valid fields |
| 198 | +* Remote validation of username, to check if it is already taken (try "Peter", "asdf" or "George") |
| 199 | + |
| 200 | +## [A multipart "buy&sell a house" form](https://jqueryvalidation.org/files/demo/multipart/) |
| 201 | +Contributed by Michael Evangelista, showing a multipart form for buying and selling houses. |
| 202 | + |
| 203 | +*Notable features of the demo:* |
| 204 | + |
| 205 | +* Multipart, implemented using the jQuery UI accordion and a custom method to check if an element is on the current page when validated |
| 206 | +* Integration with masked-input plugin, see Phone and Zip fields |
| 207 | + |
| 208 | +## [Using remote validation to help with captchas](https://jqueryvalidation.org/files/demo/captcha/) |
| 209 | +Features remote validation for helping the user to fill out captchas. |
| 210 | + |
| 211 | +*Notable features of the demo:* |
| 212 | + |
| 213 | +* Remote validation to check if the user entered the correct captcha, without forcing him to submit the form first |
0 commit comments