5.19. Form

The form generates the fields automatically using very coarse logic. A String, int, or double will result in a TextField alike, regardless of the meaning of the field. You might want to have a city name to be input with a combo box, for example. You can create such custom fields by implementing the createField() method in the FormFieldFactory interface.

The default implementation, DefaultFieldFactory is shared with the Table component: it also implements the TableFieldFactory interface. This allows the DefaultFieldFactory to create the fields for both purposes with the same logic. It is usually simplest to just extend the default implementation instead of implementing the interfaces from scratch. You should consult the source code of DefaultFieldFactory to see how it works; you may want to reimplement createFieldByPropertyType(), which actually creates the fields by type, instead of the createField().

Below is an example of implementing the FormFieldFactory interface for a specific form, using the names of the fields of the form to create the editable field components.

class MyFieldFactory implements FormFieldFactory {
    public Field createField(Item item, Object propertyId,
                             Component uiContext) {
        // Identify the fields by their Property ID.
        String pid = (String) propertyId;
        if ("name".equals(pid)) {
            return new TextField("Name");
        } else if ("city".equals(pid)) {
            Select select = new Select("City");
            select.addItem("Berlin");
            select.addItem("Helsinki");
            select.addItem("London");
            select.addItem("New York");
            select.addItem("Turku");
            select.setNewItemsAllowed(true);
            return select;
        }
        
        return null; // Invalid field (property) name.
    }
}

You set a Form to use a custom field factory with setFormFieldFactory():

form.setFormFieldFactory(new MyFieldFactory());

Validators check the validity of input and, if the input is invalid, can provide an error message through an exception. Validators are classes that implement the Validator interface. The interface has two methods that you must implement: isValid() that returns the success or failure as a truth value, and validate(), which reports a failure with an exception. The exception can be associated with an error message describing the details of the error.

Simple validators that only need to produce a single error message in case the validation fails can inherit from AbstractValidator or AbstractStringValidator. The Vaadin also provides a number of standard validators, including IntegerValidator and DoubleValidator for validating numerical input, StringLengthValidator, EmailValidator and the more general RegexpValidator for checking that a string matches a Java regular expression:

// Postal code that must be 5 digits (10000-99999).
TextField field = new TextField("Postal Code");
field.setColumns(5);

// Create the validator
Validator postalCodeValidator = new RegexpValidator(
    "[1-9][0-9]{4}", "Postal code must be a number 10000-99999.");
field.addValidator(postalCodeValidator);

If you are using a custom FieldFactory to generate the fields, you may want to set the validators for fields there. It is useful to have the form in immediate mode:

// Set the form to act immediately on user input. This is
// necessary for the validation of the fields to occur immediately
// when the input focus changes and not just on commit.
form.setImmediate(true);

Validation is done always when you call the commit() method of the Form.

// The Commit button calls form.commit().
Button commit = new Button("Commit", form, "commit");

If any of the validators in the form fail, the commit will fail and a validation exception message is displayed in the error indicator of the form. If the commit is successful, the input data is written to the data source. Notice that commit() also implicitly sets setValidationVisible(true) (if setValidationVisibleOnCommit() is true, as is the default). This makes the error indicators visible even if they were previously not visible.

For cases in which more complex error handling is required, the validator can also implement the Validator interface directly:

// Create the validator
Validator postalCodeValidator = new Validator() {

    // The isValid() method returns simply a boolean value, so
    // it can not return an error message.
    public boolean isValid(Object value) {
        if (value == null || !(value instanceof String)) {
            return false;
        }

        return ((String) value).matches("[1-9][0-9]{4}");
    }

    // Upon failure, the validate() method throws an exception
    // with an error message.
    public void validate(Object value)
                throws InvalidValueException {
        if (!isValid(value)) {
            if (value != null &&
                value.toString().startsWith("0")) {
                throw new InvalidValueException(
                    "Postal code must not start with a zero.");
            } else {
                throw new InvalidValueException(
                    "Postal code must be a number 10000-99999.");
            }
        }
    }
};

Setting a field as required outside a form is usually just a visual clue to the user. Leaving a required field empty does not display any error indicator in the empty field as a failed validation does. However, if you set a form field as required with setRequired(true) and give an error message with setRequiredError() and the user leaves the required field empty, the form will display the error message in its error indicator.

form.getField("name").setRequired(true);
form.getField("name").setRequiredError("Name is missing");
form.getField("address").setRequired(true); // No error message

To have the validation done immediately when the fields lose focus, you should set the form as immediate, as was done in the section above.