Skip to content

Client side validation

Jump to bottom
marksreeves edited this page Oct 11, 2016 · 11 revisions

Client side input validation is based on HTML5 validation as implemented in several common web browsers. It has been introduced to meet requirements for passing WCAG 2.0 guideline 3.3 at level AA particularly SCR18: Providing client-side validation and alert and SCR32: Providing client-side validation and adding error text via the DOM.

Warning!

There are significant problems with placing form controls in closed tabs or collapsed sections since these controls are hidden from the user. In general this situation should be avoided whenever possible.

This is a failure of a simple design principle that the user should be able to perceive all required controls. For information about controls inside WSubordinateControl targets, as well as controls which are themselves WSubordinateControl targets, see the WSubordinateControl documentation.

Summary of Accessibility Requirements

Client side validation of input is part of meeting the WCAG 2.0 level AA requirements of Guideline 3.3 Minimize Errors. It specifically addresses Success Criterion 3.3.1 Error Identification.

We approach this requirement by ensuring an application is capable of meeting the 'sufficient criteria':

  • G83: Providing text descriptions to identify required fields that were not completed through WValidationErrors
  • SCR18: Providing client-side validation and alert (Scripting)
  • G84: Providing a text description when the user provides information that is not in the list of allowed values through WValidationErrors
  • G85: Providing a text description when user input falls outside the required format or values through WValidationErrors
  • SCR18: Providing client-side validation and alert (Scripting)
  • SCR32: Providing client-side validation and adding error text via the DOM (Scripting)

Native HTML5 Input validation

Some user agents provide in built input validation for fields which are marked as required and for some constraints around other input types. For example a WNumberField transforms to a HTML INPUT Element of type number and supports max and min settings. Some user agents will prevent a form submission if the value entered is not numeric or is outside of the constraints and some may silently change or remove content which is not valid for that field.

We do not prevent this native validation but it is currently insufficiently mature or rich to meet requirements. Therefore we implement a custom validation scenario which, if it finds invalid input, is sufficient to prevent the user agent HTML5 validation from occurring.

User agent variations

Some user agents may undertake client side validation of input for some form controls under some conditions. The user agent may or may not output a message to the user. Where such a message is output the format, content and appearance of the message is not directly configurable by any WComponents application.

Most modern browsers, for example, will either not accept non-numeric content into a WNumberField or will accept the entry but silently remove the content when the user leaves the field.

Where a WComponent implements client side validation we attempt to explicitly prevent user agent messaging for the same validation errors. We do not, however, make any attempt to prevent the user agent from overriding or preventing invalid entry nor do we explicitly prevent a user agent from undertaking any content validation. In cases where a user chooses to disable JavaScript for part of a transaction the WComponent client side validation may not be able to prevent native validation.

Any of these may result in silent failure of poorly designed applications.

Implementing Client side validation

There are two ways to implement client side validation. It can be built into a theme or it can be added to an individual application or even an individual view in an application.

The validation JavaScript is built into all themes but is only loaded if it is included in the theme's JavaScript includes or manually required. Adding custom JavaScript is covered elsewhere but a sample script to include client validation is shown below:

require(["wc/ui/validation/all"]);

Custom Validation

We have modelled the custom validation as closely as possible on the most mature practices of user agents supporting HTML5 validation. WComponents custom validation is triggered and prevented by exactly the same mechanisms as native validation, therefore we do not turn off native validation. If the custom validation mechanism fails for some reason then native validation will take over. An extensive list of custom validation messages is supplied in the page [Client side validation messages].

Validation Summary

The table below indicates all interactions which cause a WComponents form to be submitted and whether it instigates client side validation.

Component Input Validation Notes
All WComponents with submitOnChange ✓ 1
WButton with cancel ✕ 4
WButton ✓ 1 3
[[WCancelButton WButton]] ✕
[[WConfirmButton WButton]] ✓
WMenuItem with cancel ✕ 4
WMenuItem with submit ✓

In addition the following components cause navigation or submission-like behaviour but do not trigger a form submission and will not cause client side validation:

What is validated

The following components or aspects of components have some degree of client side validation:

  • Any control with its required property set "true" except WDropdown 5
  • WFieldSet with its required property set "true" is tested to determine if at least one interactive control is 'complete' according to the control's mechanism to meet its own required state check
  • WEmailField has a primitive test that any content entered is likely to be in an email format
  • WDateField if the min or max property is set then the date entered is at lease min and/or no later than max
  • WNumberField if any input is entered it is checked that it is numeric and meets the constraints of the min and max properties if set
  • WTextField, WMultiTextField and WPhoneNumberField with a pattern property is tested against that mask
  • WTextField, WMultiTextField, WPasswordField, WPhoneNumberField and WTextArea with a minLength property is tested against that length
  • WTextArea with a maxLength property set is tested against that length2
  • WComponents which are multi select controls if the min and/or max properties are set then validation ensures that if any selection is made at all then at least min and/or no more than max options are selected. The single exeption to this is WMultiDropdown when min is "1" then the component will always be in a valid state as it does not support null selection 6.

All constraint checking other than for required is ignored if the control does not have any input/selection.

Controls excluded from client side validation

Any control which would normally be subject to client side validation according to the outline above will not be validated if:

The reason for this is that the content of such a tab or collapsible cannot be re-fetched in its current state so raising a client-side validation error will cause the form submission to fail silently since the validation error will be in a closed WTab/WCollapsible and therefore not able to be seen by the user; and if the WTab/WCollapsible was re-opened to show the validation errors the content would be refetched from the server cancelling the client validation and removing the error messages.

Controls which are in closed WTab or WCollapsible content are currently excluded from validation. This is under review and may change.

WDropdown

WDropdown is not exempt from mandatory field validation but will never fail a selection test unless the field has been programmatically manipulated 5.

When validation occurs

Client side validation occurs when:

  • a user fires a WButton or WConfirmButton to submit the page; or
  • the user interacted with a control with its [submitOnChange|Submit on change] property set "true";

Validation does not take place if the control is a WAjaxControl trigger as the page is not 'submitted'.

Form submissions excluded from client side validation

In order to meet WCAG 2.0 guidelines client side validation should occur any time data is submitted to the server. Triggering a WCancelButton provides for an explicit cancellation of data even though the state of the form is submitted to the server and is therefore exempt from client side validation, which in any case would make no sense since we would be expecting users to enter content just so it could be thrown away.

In addition some interactions involve a transient state and may be deemed to not submit final form data even though they do submit the state of the form. These are excluded from client side validation but may be included in future releases in order to meet more exacting accessibility requirements:

Notes

  1. These components will not trigger validation if the component is also a WAjaxControl trigger.
  2. WTextField, WMultiTextField, WPasswordField, WPhoneNumberField and WEmailField have a maxLength property but this is not tested during client side validation as the input to these controls is truncated when the maxLength is reached.
  3. WButton does not instigate client side validation if it is a table action of a [WTable].
  4. WCancelButton, WLink and WMenuItem may provide an [unsaved changes warning|Unsaved Changes Warnings] to the user.
  5. WDropdown and WMultiDropdown are subject to mandatory validation but do not support null selection and the component's first option is deemed to be selected if no other selection has been explicitly made. Setting the required property on a WDropdown or WMultiDropdown is a design error.
  6. WMultiDropdown does not support null selection (as described in note 5 above) and therefore a min of "1" will always be deemed to be met.

Further Information

Some start pages

Clone this wiki locally