Skip to content

Client side validation

Jump to bottom
Mark Reeves edited this page Dec 28, 2017 · 11 revisions

TODO: This document contains links to W3C/WAI resources which may be out of date. I would check them but I am currently stuck in a 747 @10000m with no web access!!

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.

WComponents client validation is triggered and prevented by exactly the same mechanisms as 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.

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"]);

When validation occurs

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
Components with SubmitOnChange ✓ 1
WButton in a cancel state ✕ 4
WButton ✓ 1 3
WMenuItem in a cancel state ✕ 4
WMenuItem with an Action ✓

Validation does not take place if the control is a WAjaxControl trigger as the page is not 'submitted' unless the invoking WButton or WMenuItem has an explicit validation target which matches at least one of the ajax targets.

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, or a WMenuItem in a cancel state, 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.

What is validated

The in-built client validation covers all validation scenarios which are obtainable from inspecting the constraints of WComponent form controls and WFieldSet. It may be extended to cover custom validation scenarios within an application using the public members of the JavaScript module wc/ui/validation/validationManager which uses a pub-sub model. This is not covered in this document.

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

  • Any control in a mandatory state 5;
  • WFieldSet in a mandatory state 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 based on HTML5 specification of an email address for the purposes of that field;
  • WDateField if an earliest or latest date is set then the date entered is at least the earliest and/or no later than the latest;
  • 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 length 2;
  • 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.

All constraint checking, other than for mandatory field completion, 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:

  • Controls which are hidden from the user by a WSubordinateControl are not validated as they are out of the current workflow and are treated as if they were not present.
  • Controls which are in the content content of closed WTab or WCollapsible (of modes CLIENT, LAZY or EAGER) are currently excluded from validation. This is under review and may change.
  • The control is in a WTab or WCollapsible of mode DYNAMIC; and
    • the WTab/WCollapsible has been opened (so that the control is present in the UI); and
    • the WTab/WCollapsible has then been closed prior to validation. 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.

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.

Validating parts of a form

The default behaviour of a validating form submission is to validate the whole of the current form. If a WButton (or similar submitting control) should only validate a part of a form then it should implement a ValidatingAction. The part of the form validated is then limited to the validation region supplied to the ValidatingAction.

This feature can be used as a validation loophole by making a control validate only itself or an empty form region to prevent it triggering any client-side validation. This loophole is strongly discouraged.

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
  • 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 attempt to prevent this native validation but it is currently insufficiently mature or rich to meet requirements.

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.

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 and WMenuItem may provide a confirmation message to the user before validation occurs.
  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 will only be honourable if at least one option is set as being a null option or has a value of null.

Further Information

Some start pages

Clone this wiki locally