ULC Validation ComponentsForm-based applications need to navigate the user through text fields and other components that are sometimes either mandatory or impose constraints on the acceptable input.
ULC Base supports mandatory fields with specified client-side enabling, such that a trailing action can only be selected when a field is filled. ULC Base also supports constraints on fields with IDataTypes.
This extension adds a ULCValidationTextField that provides an enhanced and customizable client-side feedback for these purposes. Additionally the following mandatory components: ULCMandatoryTextArea, ULCMandatoryComboBox and ULCMandatoryButtonGroup are provided. This extension builds means that ULC Base already provides.
The enhanced feedback includes:
- a customizable background color for mandatory components that falls back to the default color as soon as a value is entered
- a customizable border color for for mandatory components that stays around the field as long as it is mandatory (regardless of the input)
- a customizable warning background color for the validation text field used if the input violates a DataType constraint of status 'warning'
- a customizable error background color for the validation text field used if the input violates a DataType constraint of status 'error'
- an optional List of all current errors and warnings of all components that share a common validation model
- an optional Table of all current errors and warnings of all components that share a common validation model
- errors and warnings are displayed with an icon and explaining message where the lack of input for mandatory components is treated like errors
- three types of validation triggering are supported: validation can be applied for every keystroke, on selection changes or on focus lost
All mandatory and validation components can also serve as a client-side Enabler, in which case it obeys the following logic for enabling:
- mandatory fields may not be empty
- non-mandatory fields are allowed to be empty
- the validation state may be warning but not error
How To UseThe usage concept and the implementation is based on the JGoodies Validation Framework .
You instantiate, configure, and use a ULCValidationTextField like a ULCTextField with three additional parameters:
- an ULCValidationModel that can be shared between multiple components to collect all their warnings and errors, e.g. for collected display in a list or a table
- a key that is used to connect the component with possible messages in the model
- a behaviour type (validation when key typed, selection changes or focus lost)
// create a model to share results ULCValidationModel model = new ULCValidationModel(); // now the validation text field with key and behaviour type ULCValidationTextField date = new ULCValidationTextField(model, "date", ValidationConstants.TYPE_FOCUS_LOST); // now create a mandatory text area with key and behaviour type ULCMandatoryTextArea textArea = new ULCMandatoryTextArea(model, "textArea", ValidationConstants.TYPE_KEY_TYPED);
The components can be controlled with a number of getter/setter methods for its properties.Besides this, they are ordinary ULCComponents.
To the ULCValidationTextField you can assign a DataType after creation.
An ordinary ULC DataType is wrapped for this purpose in a ULCValidationDataType that connects the DataType with a ValidationMessage. A ValidationMessage represents what you see in list of warnings/errors. For the given key, it stores the descriptive user explanation and a classification of ValidationConstants.STATUS_ERROR or ValidationConstants.STATUS_WARNING.
// Example using DateDataType // create whatever DataType ULCDateDataType dateDataType = new ULCDateDataType(); String descr = "expected: date formatted like "+dateDataType.getFormatString(); // set the DataType wrapped together with a message and classification date.setDataType(new ULCValidationDataType(dateDataType, new ValidationMessage(date.getKey(), descr, ValidationConstants.STATUS_ERROR)));
See the Javadoc for more details about available methods.