WValidationErrors
WValidationErrors is a component for reporting input errors to users. The errors are generally automatically generated but custom messages are able to be specified. An error message must be a simple string.
WValidationErrors writes error messages from the server application. This means the user will have already undertaken a submission (or ajax request) before receiving error messages which is a sub-optimal experience. Validation of most common scenarios is available purely in the client by using Client side validation either built into the theme or as a script addition per required page.
- Creating WValidationErrors
- UI Artefacts
- WValidationErrors error message
- Unusual error states
- Related Components
- Further information
WValidationErrors are closely related to WMessages and the mechanism for reporting messages is mostly common between them. A WMessages component is added to the UI and validation scenarios and ValidatingActions use this WMessages component as the target for writing validation errors.
// common to have messages as a class-level member so we can refer to it
private final WMessages messages = new WMessages();
// ...
// whilst building the component tree the messages are usually above the area to
// which the messages will apply...
add(messages);
add(containerOfValidatableComponents);
// ...
// then when creating a validating action we use the component to
// validate and the location of messages
validatingButton.setAction(new ValidatingAction(
messages.getValidationErrors(), containerOfValidatableComponents) {
@Override
public void executeOnValid(final ActionEvent event) {
// do something
}
// optionally set a custom error function
@Override
public void executeOnError() {
// do something when invalid
}
});Refer to the wcomponents-examples module, validation package.
WValidationErrors may be used instead of WMessages if the view is to contain only validation errors without other messaging to the user. This could be useful for smaller validation containers within a full view where validation may occur via an ajax request rather than a full page refresh.
// create a WValidationErrors component
private final WValidationErrors errors = new WValidationErrors();
// assume we have a validation target which is an AjaxTarget
private final WPanel target = new WPanel();
// and a button which will cause validation as part of an ajax request
private final WButton validatingAjaxButton = new WButton("Validate");
// ...
// set up the validating button - maybe in a constructor, maybe elsewhere
// make it ajax-y
validatingAjaxButton.setAjaxTarget(target);
// add a validating action using the WValidationErrors component
validatingAjaxButton.setAction(new ValidatingAction(errors, target) {
// ...
});Note that in the code example above the WValidationErrors component is used in creating the ValidatingAction whereas in the example using WMessages above that the WValidationErrors used in creating the ValidatingAction had to be extracted from the WMessages component.
Default validation is used when a ValidatingAction is invoked on a component which does not have a customised validation scenario. Default validation will ensure mandatory fields are complete and fields with set constraints meet those constraints. For example validating a WNumberField which has a minimum and/or maximum value set will ensure any entered value is within that range and report a default error to the user if it is not.
The default errors may be found in the wcomponents-i18n module.
From WComponents 1.4 onwards WValidationErrors creates only an error list box. In-situ errors are controlled by the component for all Diagnosable components (See WComponents form controls and WFieldSet). For error messages related to other UI constructs an in-context error message may be added using WFieldErrorIndicator.
Before WComponents 1.4 WValidationErrors caused two UI artefacts.
- A message box containing all of the error messages as links to the components in an error state is output. This is output at the point at which the WValidationErrors component is added to the UI. This should generally be at the top of the main input section or the part of the form being validated. This is visually and structurally identical to a WMessageBox of type
ERROR. It outputs non-phrasing content so must not be placed in WComponents which must only contain phrasing content.
- The second UI artifact is an in context error message attached to the WComponent which is in an error state. This repeats the error message without it being wrapped in a link. This message is a span element is placed in one of three places:
- for WComponents which output a compound form control, WFieldSet, WMenu or WTable the error message is placed as the last item within the components outer wrapper element;
- for WCheckBox and WRadioButton the error message is placed immediately after the component's WLabel; and
- for all other WComponents which may be in an error state the error message is placed immediately after the form control.
In the second and third cases the position of the error message will only be correct if the WComponent in an error state is enclosed in a suitable layout container. This is normally the case but issues may arise if, for example, a set of input components are placed in a single layout container (such as a single cell of a FlowLayout) and separated only by white space. This situation is very unlikely to occur since it is normal practice to use the various layout tools to undertake structural layout and will never occur if WFieldLayout is used to create the layouts for form controls.
There are default error messages for common input constraints (such as mandatory inputs). These defaults are set using run-time properties. These properties, and their default values, may be seen in the wcomponents-i18n module.
The error messages for input controls, for example, use the text content of the WLabel associated with the form input component and, for an incomplete mandatory field as an example, is of the form:
Please enter [label text content]
If a custom error message is required, or custom validation sceanrios are to be created, then the error message must be explicitly specified for each such component in each target language.
The error message must be a simple text string to meet WCAG 2.0 guideline 3.3.1 (level A).
For simple (labelable) form controls which may be in an error state (this excludes the labelable buttons) the indication of an error state is the presence of the in-context error message and the component itself is marked with the WAI-ARIA state "aria-invalid='true'".
WComponents which output a compound form control and WFieldSet have the in-context error message placed within a border (determined by theme).
Any WComponent may be placed into an error state and be associated with a WValidationErrors message due to an old and poorly considered Java API. Before WComponents 1.4 some components would try to track their error state and report it with an in-context message. From WCompoents 1.4 onwards any such quirky error state must be accompanied by an explicit WFieldErrorIndicator to place the error message in context.
WMenu, WFieldSet and WTable cannot themselves be in an error state, after all, they are not input controls. The support for placing these WComponents into an error state is to indicate that there is an error with some part of that control.
For WTable, for example, this error state may indicate that some part of particular rows or columns must be completed. For example a table column may include a group of WCheckBox components, one per row, where at least one WCheckBox must be checked. It would be incorrect to mark every WCheckBox as mandatory since that would mean that every WCheckBox must be checked and would result in an individual error message for each WCheckBox. A custom validation scenario can be created for this case and the validation error be associated with the WTable. In this case a WFieldErrorIndicator should be placed immediately after the WTable.
With WFieldSet the case is a little more clear. A WFieldSet can be marked as mandatory which implies that at least one field within the WFieldSet must be completed. As with the WTable example above it would be incorrect to mark each field as mandatory. The custom validation scenario would mark the WFieldSet as being invalid. A typical example of this is a WFieldSet for ascertaining a telephone number and is described in more detail in the documentation for WFieldSet. WFieldSet is the recommended way to group sets of fields which are related to a semantic single purpose so WFieldSet is considered a Diagnosable component and will control its own in-context messaging without use of a WFieldErrorIndicator or WFieldWarningIndicator.
WMenu does support selection of WMenuItem components within it. The error state of a WMenu would then be a case similar to that of WTable outlined above where a failure to select a required number of WMenuItems would trigger a custom validation scenario. This would be considered a very unusual UI construction but can be catered for by placing a WFieldErrorIndicator in an appropriate location relative to the WMenu.
If a design requires this type of validation then the validation scenario and custom error message(s) must be explicitly specified.