ULC Validation Components

Form-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 the above can be handled at the client side without server roundtrips but when a server roundtrip happens anyway, all validation states and messages are also available on the server (i.e. in your application).

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 Use

The 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.

How It Is Implemented

Validation and mandatory components are extensions with a client and a server half, following the usual way of implementing ULC Extensions. The implementation is based on the JGoodies Validation Framework with a few tweaks. A customized version of the framework is part of the client-side extension.