Summary

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

Status

API status: experimental
Web resource key: com.atlassian.auiplugin:aui-form-validation
AMD Module key: require('aui/form-validation')
Experimental API: 5.5

Examples

Code

Setup

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.

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 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
  • 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 todata-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 messages will be displayed below 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

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 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, ['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
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).