Validation rules are run when data is provided to the system, to check that it the data conforms. This guide focuses on validating data which is inputted manually by users via fields.
Validation can be invoked by one a number of two actions, either when . When the user:
Dirties a an individual field - , i.e. when they enter some content and then move away from the field - check this.
Selects “Save”
...
on the fly, as they as entering content into a field. This is the primary validation method.
Performs a “Save” action covering multiple fields. Fields which cannot be validated when they are dirtied should instead be validated on an action such as “Save” or “Confirm”. Actions which trigger a save can be made on the client-side or the back-end.
Client-side: When fields are validated in bulk on the client-side, any invalid fields should apply the main guidelines defined below.
Server side: A long term goal is for fields validated on the server side to also follow the main guidelines. As this is not feasible at the moment a separate set of guidelines exists for server side validation.
When a field contains invalid data it is in an “error state”. When in this state:
The data should not be saved
An error or warning message should be displayed beneath the field
Invalid data should not be saved
The user should be able to move freely around the form or page and not be locked to the field
Any save options should be inactive, unless validation for the field can only be run on “save”
If the user leaves the form or page they should see the standard “Unsaved changes” warning [link to be added]
Note that a field can be in a warning state, rather than an error state. Fields in a warning state can still be saved and are not considered to be invalid.
Feedback message
When a field contains invalid content, it should be made clear to the user what the problem is and how they can fix it. The message
Error messages should always start with the field label and be short.include the name of the field, to support accessibility guidelines.
Messages should be informative yet short. We should avoid using words such as “please”. [add more stop words?]
Empty mandatory field
When a mandatory field is empty the error message should state: “Enter a/an/the {field label}”.Insert example.
...
Invalid format
When the input format is wrong, the a field contains invalid content the error message should always start with the field label and be informative but kept short. The error message should follow the format:
...
Fields expecting an email address check for the format name@domain. The error message should read:
“{field label} must be an a valid email address”
Fields expecting a URL check that http or https is included. The error message should read:
“{field label} must begin “http” or “https”
Invalid content
When a field’s content does not conform to any data restriction rules in place, the error message should follow the same format as described. format:
“{field label} must {description}”
For example, “Latitude must be a number between -90 and 90”
...
Each validation message should be displayed underneath the relevant field. If the message takes up the full width of the field it should then wrap onto another row.
When a field in an error or warning state:
The field background
...
color should change to the standard error
...
background
...
color
Field label text and feedback text
...
be displayed in the standard error foreground color [to be reviewed]
A field may instead be in a warning state. In this case the warning styles would be applied.
Dependent fields
Rules controlling the validity of data can cover multiple fields, creating dependencies between their content.
When a dependent field’s content does not conform to the rules in place, the error message should follow the format:
“{field label} must {description}”
For example, “End date must be equal to or after the start date”
When a dependency is in place, the value of one field can affect the state of one or more other fields and the behaviour varies depending on the type of rule which is in place.
Rules changing field visibility or availability
Fields can become active or warning foreground colourinactive, or completely hidden from view, based on the value of another field. For example:
When the value of field x = “yes” then field y becomes active and mandatory.
For this type of rule the user will not normally see any validation issues. When a field containing a value is made inactive the value should remain visible in the inactive field. [review this] There is no need to display a warning.
Rules changing the allowable values
The set of allowable values for one field can change depending on the value of another. For example, for an Item Type mapping when the “From context” is set to ”DCB”, restrict the set of values available in the “To context” to CIRC, NONCIRC and CIRCAV.
...
In the above example, if the user was to change "From context" from “DCB” to “Lindenwood”, then “CIRC” is no longer a valid value for "To context" and so:
"CIRC" becomes an invalid value for "To context" and is substituted for a valid value: "DCB"
"To context" is put into a warning state to indicate that its value has changed
...
Rules fixing the allowable values
Some dependencies have fixed rules affecting the acceptable values for a field. For example, when entering a date range the end date cannot be before the start date. In this case, neither field is correct so they are both in an error state.
...
Validation on save
Fields should be validated on the fly wherever possible.
When validation is instead run on save a user triggered “save” action and errors are found, some guidelines, additional to those described above, must be applied:
All invalid fields should be highlighted.displayed in the error state
Focus should move to the first invalid field
An “error” toast should be displayed, letting the user know their submission contains errors and has not been saved. The toast should display:
A heading “Error”
The text “The {name/entity} was not saved. One or more fields are invalid. Please correct any errors and retry”
...
Server side validation
When fields are validated on the server side, it is not possible to put an individual field into an “error” state in the UI. Instead any errors must be indicated in a toast message. The longer term goal is to bring server side validation inline with the above guidelines.
The toast should display:
A heading “Error”
The text “The {name/entity} was not saved. One or more fields are invalid. Please fix the following issue(s) and retry”
A list of errors in the form: {field label} must {description}
...
The toast should display either until the user closes it, or when they re-trigger the validation.