Form validation is used to provide an interface for validating form fields, and displaying feedback on problems.
| API status: | experimental |
|---|---|
| Included in AUI core? | Not in core You must explicitly require the web resource key. |
| Web resource key: |
com.atlassian.auiplugin:aui-form-validation
|
| AMD Module key: |
require('aui/form-validation')
|
| Experimental API: | 5.5 |
Ensure you've added some field validators.
Note the use of the minlength attribute. This attribute specifies minimum length of the input value (the length must be at least 10 characters, or validation will fail).
In addition, data-aui-validation-field must be present for validation to occur.
This is enough for validation to be set up on the field – no further initialisation is necessary. The library will take care of binding events and adding markup to any input with a data-aui-validation-* data attribute.
Form validation arguments and options are expressed through markup.
Arguments for the provided validators are configured in data attributes beginning with the data-aui-validation-*prefix.
| Data attribute | Description |
|---|---|
|
The length of the field's value must be greater than or equal to the minlength, and less than
or equal to the maxlength.
|
data-aui-validation-matchingfield |
The id of an input that must have a matching value |
data-aui-validation-doesnotcontain |
Some text that the value of the field cannot contain |
|
A regex pattern that the field must match |
|
This is a required field, and the field's value must have a length greater than zero. |
|
The numerical value of this field must be greater than or equal to this minimum. Note that it is different
to minlength / maxlength, as it compares a number's value, rather than a string's length.
|
data-aui-validation-dateformat |
A date format that this field must comply with. Can contain any separator symbols, or the following symbols,
which represent different date components:
|
|
The number of checkboxes checked in this field must be greater than or equal todata-aui-validation-minchecked,
and less than or equal to data-aui-validation-maxchecked |
All of the above validators take an additional argument: data-aui-validation-...-msg. This sets a custom message that will be shown to the user when the validation fails.
Each argument is passed to AJS.format, with the value of the argument passed in as the first value. {0} will be replaced with the arguments value. For example:
The exception to this is data-aui-validation-matchingfield, which is passed the first field's argument in {0}and the second field's argument in {1}.
Options affect the behaviour of all validators running on a field. They are configured in data attributes.
| Data attribute | Description |
|---|---|
data-aui-validation-when |
The event that will trigger validation. It can be any DOM event fired on the field, such as keyup or change, or a custom event that you will initiate yourself.
Default: |
data-aui-validation-watchfield |
The id of an additional element that can also trigger validation events (the event specified by data-aui-validation-when)
Default: Unspecified (only watches self) |
data-aui-validation-displayfield |
The Unspecified (self) |
data-aui-validation-novalidate |
If this argument is present, validation is completely disabled on the field |
data-aui-tooltip-position |
The position that the the tooltip will be displayed on. Can be one of 'top', 'bottom' or 'side'.
|
To prevent users from submitting invalid forms, the form validation library will intercept submitevents that contain invalid, validating, or unvalidated elements. If the form is still being validated when a submit event occurs, submission will be delayed until validation completes.
When the form is submitted in a valid state, the event aui-valid-submit is triggered. If the submit event should be prevented, preventing the aui-valid-submit event will prevent submit too.
A number of additional events are triggered on fields using the form validation library.
| Event name | Description |
|---|---|
aui-stop-typing |
Triggered on a field when there have been no |
Additional validators can be registered and your own validators defined. They can be synchronous or asynchronous, and may validate or invalidate based on an element in any way.
The AJS.formValidation.register function takes the following arguments
| Argument name | Description |
|---|---|
trigger |
The trigger that will cause a validator to be run on an element. Can be either an array of arguments to match, or a selector string to match. If an array of validation arguments are provided, validation will be triggered on elements with the corresponding data attributes specified. For example, If a string is provided, validation will be triggered on elements that match this selector. For example, a trigger of |
validationFunction |
A function containing the logic of the validator. This function takes the argument field(see below for more information on this). |
The function validationFunction(field) is the core of a validator, containing the logic of whether or not a field is valid. It takes the following arguments
| Argument name | Description |
|---|---|
field |
The field that the validator is being asked to validate. It contains:
|
After performing whatever logic is necessary with the field.el object to validate or invalidate, all code paths must execute either field.validate() or field.invalidate('message'). The reason given may be shown on the field as an error (see AJS.format()for formatting these strings).