Field Components

Fields are components that have a value that the user can change through the user interface. Field components illustrates the inheritance relationships and the important interfaces and base classes.

field diagram hi

Field components

Field components are built upon the framework defined in the Field interface and the AbstractField base class. AbstractField is the base class for all field components. In addition to the component features inherited from AbstractComponent, it implements a number of features defined in Property, Buffered, Validatable, and Component.Focusable interfaces.

The description of the field interfaces and base classes is broken down in the following sections.

The Field Interface

The Field interface inherits the Component superinterface and also the Property interface to have a value for the field. AbstractField is the only class implementing the Field interface directly. The relationships are illustrated in Field interface inheritance.

field interface hi

Field interface inheritance

You can set the field value with the setValue() and read with the getValue() method defined in the Property interface. The actual value type depends on the component.

The Field interface defines a number of properties, which you can access with the corresponding setters and getters.

required

When enabled, a required indicator (usually the asterisk * character) is displayed on the left, above, or right the field, depending on the containing layout and whether the field has a caption. If such fields are validated but are empty and the requiredError property (see below) is set, an error indicator is shown and the component error is set to the text defined with the error property. Without validation, the required indicator is merely a visual guide.

requiredError

Defines the error message to show when a value is required, but none is entered. The error message is set as the component error for the field and is usually displayed in a tooltip when the mouse pointer hovers over the error indicator.

Data Binding and Conversions

Fields are strongly coupled with the Vaadin data model. The field value is handled as a Property of the field component, as documented in “Properties”. Selection fields allow management of the selectable items through the Container interface.

Fields are editors for some particular type. For example, TextField allows editing String values. When bound to a data source, the property type of the data model can be something different, say an Integer. Converters are used for converting the values between the representation and the model. They are described in “Converting Between Property Type and Representation”.

Handling Field Value Changes

Field inherits Property.ValueChangeListener to allow listening for field value changes and Property.Editor to allow editing values.

When the value of a field changes, a Property.ValueChangeEvent is triggered for the field. You should not implement the valueChange() method in a class inheriting AbstractField, as it is already implemented in AbstractField. You should instead implement the method explicitly by adding the implementing object as a listener.

Field Buffering

Field components implement the Buffered and BufferedValidatable interfaces. When buffering is enabled for a field with setBuffered(true), the value is not written to the property data source before the commit() method is called for the field. Calling commit() also runs validators added to the field, and if any fail (and the invalidCommitted is disabled), the value is not written.

Java

  1. form.addComponent(new Button("Commit",
  2.     new Button.ClickListener() {
  3.     @Override
  4.     public void buttonClick(ClickEvent event) {
  5.         try {
  6.             editor.commit();
  7.         } catch (InvalidValueException e) {
  8.             Notification.show(e.getMessage());
  9.         }
  10.     }
  11. }));

See the on-line example.

Calling discard() reads the value from the property data source to the current input.

If the fields are bound in a FieldGroup that has buffering enabled, calling commit() for the group runs validation on all fields in the group, and if successful, all the field values are written to the item data source. See “Buffering Forms”.

Field Validation

The input for a field component can be syntactically or semantically invalid. Fields implement the Validatable interface, which allows checking validity of the input with validators that implement the Validator interface. You can add validators to fields with addValidator().

Java

  1. TextField field = new TextField("Name");
  2. field.addValidator(new StringLengthValidator(
  3.     "The name must be 1-10 letters (was {0})",
  4.     1, 10, true));
  5. field.setNullRepresentation("");
  6. field.setNullSettingAllowed(true);
  7. layout.addComponent(field);

See the on-line example.

Failed validation is indicated with the error indicator of the field, described in “Error Indicator and Message”, unless disabled with setValidationVisible(false). Hovering mouse on the field displays the error message given as a parameter for the validator. If validated explicitly with validate(), as described later, the InvalidValueException is thrown if the validation fails, also carrying the error message. The value {0} in the error message string is replaced with the invalid input value.

Validators validate the property type of the field after a possible conversion, not the presentation type. For example, an IntegerRangeValidator requires that the value type of the property data source is Integer.

Built-in Validators

Vaadin includes the following built-in validators. The property value type is indicated.

BeanValidator

Validates a bean property according to annotations defined in the Bean Validation API 1.0 (JSR-303). This validator is usually not used explicitly, but they are created implicitly when binding fields in a BeanFieldGroup. Using bean validation requires an implementation library of the API. See “Bean Validation” for details.

CompositeValidator

Combines validators using logical AND and OR operators.

DateRangeValidator: Date

Checks that the date value is within the range at or between two given dates/times.

DoubleRangeValidator: Double

Checks that the double value is at or between two given values.

EmailValidator: String

Checks that the string value is a syntactically valid email address. The validated syntax is close to the RFC 822 standard regarding email addresses.

IntegerRangeValidator: Integer

Checks that the integer value is at or between two given values.

NullValidator

Checks whether the value is or is not a null value.

For the validator to be meaningful, the component must support inputting null values. For example, for selection components and TextField, inputting null values can be enabled with setNullSettingAllowed(). You also need to set the representation of null values: in selection components with setNullSelectionItemId() and in TextField with setNullRepresentation().

Setting field as required can be used for similar effect, and it also enables an indicator to indicate that a value is required.

RegexpValidator: String

Checks that the value matches with the given regular expression.

StringLengthValidator: String

Checks that the length of the input string is at or between two given lengths.

The allowNull parameter determines whether null values should be allowed for the string, regardless of the string length. A null value has zero length, so it will be invalid if the minimum length is greater than zero. Allowing null value is meaningful only if inputting null values is enabled with setNullSettingAllowed(true), and typically in such case, you want to set the null representation to empty string with setNullRepresentation(“”). Note that this parameter is deprecated and should normally be true; then you can use setRequired() (for the false case) or NullValidator.

Please see the API documentation for more details.

Automatic Validation

The validators are normally, when validationVisible is true for the field, executed implicitly on the next server request if the input has changed. If the field is in immediate mode, it (and any other fields with changed value) are validated immediately when the focus leaves the field.

Java

  1. TextField field = new TextField("Name");
  2. field.addValidator(new StringLengthValidator(
  3.     "The name must be 1-10 letters (was {0})",
  4.     1, 10, true));
  5. field.setImmediate(true);
  6. field.setNullRepresentation("");
  7. field.setNullSettingAllowed(true);
  8. layout.addComponent(field);

See the on-line example.

Explicit Validation

The validators are executed when the validate() or commit() methods are called for the field.

Java

  1. // A field with automatic validation disabled
  2. final TextField field = new TextField("Name");
  3. field.setNullRepresentation("");
  4. field.setNullSettingAllowed(true);
  5. layout.addComponent(field);
  7. // Define validation as usual
  8. field.addValidator(new StringLengthValidator(
  9.     "The name must be 1-10 letters (was {0})",
  10.     1, 10, true));
  12. // Run validation explicitly
  13. Button validate = new Button("Validate");
  14. validate.addClickListener(new ClickListener() {
  15.     @Override
  16.     public void buttonClick(ClickEvent event) {
  17.         field.setValidationVisible(false);
  18.         try {
  19.             field.validate();
  20.         } catch (InvalidValueException e) {
  21.             Notification.show(e.getMessage());
  22.             field.setValidationVisible(true);
  23.         }
  24.     }
  25. });
  26. layout.addComponent(validate);

See the on-line example.

Implementing a Custom Validator

You can create custom validators by implementing the Validator interface and implementing its validate() method. If the validation fails, the method should throw either InvalidValueException or EmptyValueException.

Java

  1. class MyValidator implements Validator {
  2.     @Override
  3.     public void validate(Object value)
  4.             throws InvalidValueException {
  5.         if (!(value instanceof String &&
  6.                 ((String)value).equals("hello")))
  7.             throw new InvalidValueException("You're impolite");
  8.     }
  9. }
  11. TextField field = new TextField("Say hello");
  12. field.addValidator(new MyValidator());
  13. field.setImmediate(true);
  14. layout.addComponent(field);

See the on-line example.

Validation in Field Groups

If the field is bound to a FieldGroup, described in “Creating Forms by Binding Fields to Items”, calling commit() for the group runs the validation for all the fields in the group, and if successful, writes the input values to the data source.