Style guide/Error handling and validation

This document is a work in progress.

This document is part of the MediaWiki style guide. This section concerns itself with form error handling and validation techniques.

Approaches in use

 * A few extensions use the assets here, such as the abandoned Extension:SignupAPI.
 * Special:ChangeEmail has very simple tooltip validation
 * the Account creation user experience test used in-field background images (green checkmark, red X, gray "in process" animation) for client-side validation
 * many forms display server-side errors in a box on top. Agora restyles this to a pink bordered box.
 * some HTMLForms display red error text below fields with problems

General notes
When validating forms, there are two possible results for any one form field:


 * Valid - the data entered by the user is valid and can be saved;
 * Invalid - the data entered by the user is unacceptable and cannot be saved.

Note that "invalid" data does not necessarily indicate an error condition - though most often this is the case. There are myriad ways in which data can be invalid and yet still acceptable for saving.

For example, MediaWiki does not (as of this writing) enforce a valid regular expression for email addresses. A user entering "qasdfasdfas" as an email address may be entering invalid data but the system will not throw an error condition.

Server-side vs. client-side validation
Field data can be validated on the client side through Javascript. This is often a desired part of a good user experience. However, field data should always be validated by the server upon submission, regardless of what client-side validation says about the matter (it is sometimes possible to trick the browser into submitting invalid forms).

As a result of this, one should never rely purely on client-side validation for success. All data must be checked by the server on a round trip submission. The server's results (success or failure) should be considered canonical.

Client-Side Validation
Certain field elements can benefit from "client-side validation". In these instances, the value entered by the user is immediately checked for validity through Javascript (either using page-local tests or server requests). These types of fields allow the user to correct known errors without submitting the form and are a powerful usability enhancement.

Live validation events are triggered when the field element loses focus. Validation successes and errors appear in-line with the form element and have icons to draw the user's attention to the result.

Live validation works best with horizontal style message placements.

Client-Side Validation Examples
Here are two examples of live validation behavior.

Password Validity
A common aspect to creating a user account involves creating a password and ensuring its accuracy. This takes two fields: password and confirm password. Both may be checked for validity.

The "Password" field can be checked for password strength and updated instantly. The "Re-Enter Password" field can be checked to ensure its value is the same as the one entered previously.

User Name Selection
User name selection can be a difficult process, especially if the desired username is popular.

If the user name is valid and acceptable, then this is validated as positive. If it is invalid (too short, or has special characters), this can be marked invalid with an error message. If it is taken, this can also be displayed (along with optional suggestions, e.g., "Jimbo Wales29").

Banner Notification
A banner notification that informs the user that an error has occurred should always appear, regardless of other error display mechanisms. This banner should inform the user that the action failed and that they (the user) should correct the specific errors below.

Optionally, a list of specific errors may be included in the banner. If the list of errors is greater than 2 or 3, however, the list should be omitted.

If the error is not tied to a specific field (e.g., "Failed to connect to the database"), then the error must be included in the error notification banner. If the errors are only system-level, then the user should not be prompted to fix them (but may be prompted to try again later or contact an administrator).

Field Local Error Notification
If at all possible, errors should be associated with the fields they are connected to with an error string that helps the user understand what happened and how to correct the error.

Fields with errors should be called out with an obvious icon to the left of the input mechanism. It should be vertically aligned with the input mechanism (below the label and any help trigger icon).

The icon should be at least 16x16 pixels in size (a red asterisk is not acceptable).

Where possible, the input mechanism should have a red border. This should be at least 2 pixels in thickness but no more than three.

Depending on the form layout and the developer's whim, field level errors can be displayed horizontally or vertically - or even a mix within the same form.

In horizontal alignment, the error list is displayed to the right of the input element. Horizontal aligments are especially good for select boxes or checkbox groupings.

In vertical alignment, the error list is displayed directly beneath the element's input mechanism. This is often the most developer-friendly way to display the error.