Binding Data to Forms

A typical application lets the user fill out structured data and maybe also browse previously entered data. The data that is being entered is typically represented in code as an instance of a business object (bean), for instance aPerson# in an HR application.

Flow provides a Binder class that the developer can use to define how the values in a business object should be bound to the fields shown in the user interface. Binder takes care of reading values from the business object and converting the user’s data between the format expected by the business object and the format expected by the field. The input entered by the user can also be validated, and the current validation status can be presented to the user in different ways.

The first step to binding fields for a form is to create a Binder and bind some input fields. There is only one Binder instance for each form and it is used for all fields in that form.

Java

  1. Binder<Person> binder = new Binder<>();
  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 to the Person class
  8.   .bind(
  9.     // Callback that loads the title from a person instance
  10.     Person::getTitle,
  11.     // Callback that saves the title in a person instance
  12.     Person::setTitle);
  14. TextField nameField = new TextField();
  16. // Shorthand for cases without extra configuration
  17. binder.bind(nameField, Person::getName, Person::setName);

When we have bound field components using our binder, we can use the binder to load values from a person into the field, let the user edit the values and finally save the values back into a person instance.

Java

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

With these basic steps, we have defined everything that is needed for loading, editing and saving values for a form.

The above example uses Java 8 method references for defining how field values are loaded and saved. It is also possible to use a lambda expression or an explicit instance of the callback interface instead of a method reference.

Java

  1. // With lambda expressions
  2. binder.bind(titleField,
  3.   person -> person.getTitle(),
  4.   (person, title) -> person.setTitle(title));
  6. // With explicit callback interface instances
  7. binder.bind(nameField,
  8.   new ValueProvider<Person, String>() {
  9.     @Override
  10.     public String apply(Person person) {
  11.       return person.getName();
  12.     }
  13.   },
  14.   new Setter<Person, String>() {
  15.     @Override
  16.     public void accept(Person person, String name) {
  17.       person.setName(name);
  18.     }
  19.   });

Binding Non-Modifiable Data

Non-modifiable data can be also bound to any component or component property with the ReadOnlyHasValue helper class. For example, we can bind a Label to display a person’s full name:

Java

  1. Label nameLabel = new Label();
  2. ReadOnlyHasValue<Person> fullName = new ReadOnlyHasValue<>(
  3.         person -> nameLabel.setText(
  4.                 person.getLastName() + ", " + person.getName()));
  5. binder.forField(fullName).bind(person -> person, null);