Binding Data to Forms

In many applications users provide structured data by completing fields in forms. This data is typically represented in code as an instance of a business object (JavaBean), for example a Person in an HR application.

The Binder class allows you to define how the values in a business object are bound to fields in the UI.

Binder reads the values in the business object and converts them from the format expected by the business object to the format expected by the field, and vice versa.

Binder can only bind components that implement the HasValue interface, for example TextField and ComboBox.

It is also possible to validate user input and present the validation status to the user in different ways.

How to Bind Form Data

The following steps include everything needed to load, edit and save values for a form. Java 8 method references are used.

To bind data to a form:

  1. Create a Binder and bind the input fields.

    Note
    		There can only be one Binder instance for each form. You should use it for all fields in the form.

    Java

    1. Binder<Person> binder = new Binder<>(Person.class);
    3. TextField titleField = new TextField();
    5. // Start by defining the Field instance to use
    6. binder.forField(titleField)
    7.         // Finalize by doing the actual binding
    8.         // to the Person class
    9.         .bind(
    10.                 // Callback that loads the title
    11.                 // from a person instance
    12.                 Person::getTitle,
    13.                 // Callback that saves the title
    14.                 // in a person instance
    15.                 Person::setTitle);
    17. TextField nameField = new TextField();
    19. // Shorthand for cases without extra configuration
    20. binder.bind(nameField, Person::getName,
    21.         Person::setName);

  2. Use the Binder to:

    1. Load values from a person into the field.

    2. Allow the user to edit the values.

    3. Save the values back into a person instance.

      Java

      1. // The person to edit
      2. // Would be loaded from the backend
      3. // in a real application
      4. Person person = new Person("John Doe", 1957);
      6. // Updates the value in each bound field component
      7. binder.readBean(person);
      9. Button saveButton = new Button("Save",
      10.     event -> {
      11.         try {
      12.             binder.writeBean(person);
      13.             // A real application would also save
      14.             // the updated person
      15.             // using the application's backend
      16.         } catch (ValidationException e) {
      17.             notifyValidationException(e);
      18.         }
      19. });
      21. // Updates the fields again with the
      22. // previously saved values
      23. Button resetButton = new Button("Reset",
      24.         event -> binder.readBean(person));

      • Every time writeBean is called, the data is validated and then copied from the UI to the business object.

      • If the data is invalid, a ValidationException that includes all errors in the data, is thrown. This is the reason writeBean is in a try/catch block.

It is also possible to use a Lambda expression, instead of a method reference.

Java

  1. // With lambda expressions
  2. binder.bind(titleField,
  3.         person -> person.getTitle(),
  4.         (person, title) -> {
  5.             person.setTitle(title);
  6.             logger.info("setTitle: {}", title);
  7.         });

Binding Read-only Data

To bind a component to read-only data, you can use a null value for the setter.

Example: Using a null value setter.

Java

  1. TextField fullName = new TextField();
  2. binder.forField(fullName)
  3.         .bind(Person::getFullName, null);

To bind components that do not implement the HasValue interface to read-only data, you can use the ReadOnlyHasValue helper class.

Example: Using the ReadOnlyHasValue helper class.

Java

  1. Label fullNameLabel = new Label();
  2. ReadOnlyHasValue<String> fullName =
  3.         new ReadOnlyHasValue<>(
  4.             text -> fullNameLabel.setText(text));
  5. binder.forField(fullName)
  6.         .bind(Person::getFullName, null);