Form validation

Ask a question Design guidelines

Summary

Form validation is used to provide an interface for validating form fields, and displaying feedback on problems.

Status

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:	`aui/form-validation`
Experimental since:	5.5

Examples

Code

Setup

Ensure you require the Form Validation module in your javascript initialisation code, as well as the AUI-provided 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.

Options

Markup configuration

Form validation arguments and options are expressed through markup.

Provided validators

Arguments for the provided validators are configured in data attributes beginning with the data-aui-validation-*prefix.

Data attribute	Description
`data-aui-validation-minlength` Deprecated `data-aui-validation-maxlength` Deprecated `minlength` `maxlength`	The length of the field's value must be less than or equal to the `minlength`, and greater 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
`data-aui-validation-pattern` Deprecated `pattern`	A regex pattern that the field must match
`data-aui-validation-required` Deprecated `required`	This is a required field, and the field's value must have a length greater than zero.
`data-aui-validation-min` Deprecated `data-aui-validation-max` Deprecated `min` `max`	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: Y: Four digit year, eg. 2014 y: Two digit year, eg. 14 m: Numerical month, eg. 03 M: Abbreviated month, eg. Mar D: Abbreviated day, eg. Mon d: Numerical day, eg. 28
`data-aui-validation-minchecked` `data-aui-validation-maxchecked`	The number of checkboxes checked in this field must be greater than or equal to`data-aui-validation-minchecked`, and less than or equal to `data-aui-validation-maxchecked`

Provided validators messages

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}.

Validation options

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: `change`
`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 `id` of the element to decorate when fields become valid or invalid. Icons and tooltips will be displayed on this field, but validation events and logic will remain on the original field. 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'. `"side"`

Form submission

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.

Field events

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 `keyup` events for some period of time. Can be used as the `data-aui-validation-when` option for validators.

Plugin validators

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.

Registering a validator

The validator.register function takes the following arguments

Argument name Description

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, `['startswith', 'endswith']` will match `data-aui-validation-startswith` or `data-aui-validation-endswith`. If a string is provided, validation will be triggered on elements that match this selector. For example, a trigger of `'[aria-required]'` will cause the validator to also be run when the `aria-required` attribute is present.
`validationFunction`	A function containing the logic of the validator. This function takes the argument `field`(see below for more information on this).

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, ['startswith', 'endswith'] will match data-aui-validation-startswith or data-aui-validation-endswith.

If a string is provided, validation will be triggered on elements that match this selector. For example, a trigger of '[aria-required]' will cause the validator to also be run when the aria-required attribute is present.

validationFunction A function containing the logic of the validator. This function takes the argument field(see below for more information on this).

Writing the validator

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

Argument name	Description
`field`	The field that the validator is being asked to validate. It contains: `field.el`: the field that validation has been requested on. `field.args`: An accessor function to retrieve validation arguments from the element.`arguments('startswith')` will access the value for `data-aui-validation-startswith`. If there is no prefixed attribute it will return the value of the unprefixed attribute (`startswith` in this case). `field.validate()`: declare that this field has passed validation `field.invalidate(message)`: declare that this field has failed validation, and possibly show the user the message provided.

field

The field that the validator is being asked to validate. It contains:

field.el: the field that validation has been requested on.
field.args: An accessor function to retrieve validation arguments from the element.arguments('startswith') will access the value for data-aui-validation-startswith. If there is no prefixed attribute it will return the value of the unprefixed attribute (startswith in this case).
field.validate(): declare that this field has passed validation
field.invalidate(message): declare that this field has failed validation, and possibly show the user the message provided.

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).