Vaadin Forms: Data Binding and Validation

Learn how to use Binder to bind a data object to input fields and validate input.

Using Vaadin Binder to Create a Form and Validate Input
Creating the Binder
Setting the Contact
Setting up Component Events
Saving, Deleting, and Closing the Form

Caution

This tutorial is for Vaadin 14.

If this is your first time trying out Vaadin, you should read the same tutorial for the latest Vaadin version instead.

In the Creating a Component chapter, you created the input fields and buttons that you need for editing contacts. In this chapter, you will bind those inputs to a Contact object to create a fully functional form with validation.

This chapter covers:

Creating a Vaadin Binder.
Binding input fields.
Field validation.

Using Vaadin Binder to Create a Form and Validate Input

A form is a collection of input fields that are connected to a data model, a Contact in this case. Forms validate user input and make it easy to get an object populated with input values from the UI.

Vaadin uses the Binder class to build forms. It binds UI fields to data object fields by name. For instance, it takes a UI field named firstName and maps it to the firstName field of the data object. Similarly, it maps the lastName field to the lastName field, and so on. This is why the field names in Contact and ContactForm are the same.

Note

Advanced Binder API

Binder also supports an advanced API where you can configure data conversions and additional validation rules. However, for this application, the simple API is sufficient.

Binder can use validation rules that are defined on the data object in the UI. This means you can run the same validations both in the browser and before saving to the database, without duplicating code.

Defining Bean Validation Rules in Java

You can define data validation rules as Java bean validation annotations on the Java class.

You can see all the applied validation rules by inspecting Contact.java. The validations are placed above the field declarations like this:

@Email
@NotEmpty
private String email = "";

Creating the Binder

Instantiate a Binder and use it to bind the input fields:

// Other fields omitted
Binder<Contact> binder = new BeanValidationBinder<>(Contact.class); 1

public ContactForm(List<Company> companies, List<Status> statuses) {
    addClassName("contact-form");
    binder.bindInstanceFields(this); 2
    // Rest of constructor omitted
}

BeanValidationBinder is a Binder that is aware of bean validation annotations. By passing it in the Contact.class, you define the type of object you are binding to.
bindInstanceFields() matches fields in Contact and ContactForm based on their names.

With these two lines of code, you’ve readied the UI fields to be connected to a contact. That’s the next step.

Setting the Contact

Next, you need to create a setter for the contact. Unlike the companies and statuses, it can change over time as a user browses through the contacts.

To do this, add the following in the ContactForm class:

public class ContactForm extends FormLayout {
    private Contact contact;

    // other methods and fields omitted

    public void setContact(Contact contact) {
        this.contact = contact; 1
        binder.readBean(contact); 2
    }
}

Save a reference to the contact, so you can save the form values back into it later.
Calls binder.readBean() to bind the values from the contact to the UI fields. readBean() copies the values from the contact to an internal model; that way you don’t overwrite values if you cancel editing.

Setting up Component Events

Vaadin comes with an event-handling system for components. You have already used it to listen to value-change events from the filter TextField in the main view. The form component should have a similar way of informing parent components of events.

The events you will fire are:

SaveEvent
DeleteEvent
CloseEvent

Add the following code at the end of the ContactForm class to define the new events:

// Events
public static abstract class ContactFormEvent extends ComponentEvent<ContactForm> {
  private Contact contact;

  protected ContactFormEvent(ContactForm source, Contact contact) { 1
    super(source, false);
    this.contact = contact;
  }

  public Contact getContact() {
    return contact;
  }
}

public static class SaveEvent extends ContactFormEvent {
  SaveEvent(ContactForm source, Contact contact) {
    super(source, contact);
  }
}

public static class DeleteEvent extends ContactFormEvent {
  DeleteEvent(ContactForm source, Contact contact) {
    super(source, contact);
  }

}

public static class CloseEvent extends ContactFormEvent {
  CloseEvent(ContactForm source) {
    super(source, null);
  }
}

public <T extends ComponentEvent<?>> Registration addListener(Class<T> eventType,
    ComponentEventListener<T> listener) { 2
  return getEventBus().addListener(eventType, listener);
}

ContactFormEvent is a common superclass for all the events. It contains the contact that was edited or deleted.
The addListener() method uses Vaadin’s event bus to register the custom event types. Select the com.vaadin import for Registration if IntelliJ asks.

Saving, Deleting, and Closing the Form

With the event types defined, you can now inform anyone using ContactForm of relevant events.

To add save, delete, and close event listeners, add the following to the ContactForm class:

private Component createButtonsLayout() {
  save.addThemeVariants(ButtonVariant.LUMO_PRIMARY);
  delete.addThemeVariants(ButtonVariant.LUMO_ERROR);
  close.addThemeVariants(ButtonVariant.LUMO_TERTIARY);

  save.addClickShortcut(Key.ENTER);
  close.addClickShortcut(Key.ESCAPE);

  save.addClickListener(event -> validateAndSave()); 1
  delete.addClickListener(event -> fireEvent(new DeleteEvent(this, contact))); 2
  close.addClickListener(event -> fireEvent(new CloseEvent(this))); 3

  binder.addStatusChangeListener(e -> save.setEnabled(binder.isValid())); 4
  return new HorizontalLayout(save, delete, close);
}

private void validateAndSave() {
  try {
    binder.writeBean(contact); 5
    fireEvent(new SaveEvent(this, contact)); 6
  } catch (ValidationException e) {
    e.printStackTrace();
  }
}

The save button calls the validateAndSave() method.
The delete button fires a delete event and passes the active contact.
The cancel button fires a close event.
Validates the form every time it changes. If it is invalid, it disables the save button to avoid invalid submissions.
Write the form contents back to the original contact.
Fire a save event, so the parent component can handle the action.

Build the project and verify that it compiles. There are no visible changes yet. In the next chapter, you will connect the form to the list view to complete the first view.

migration assistance

Download free e-book.
The complete guide is also available in an easy-to-follow PDF format.

Open in a
new tab
export class RenderBanner extends HTMLElement {
  connectedCallback() {
    this.renderBanner();
  }

  renderBanner() {
    let bannerWrapper = document.getElementById('tocBanner');

    if (bannerWrapper) {
      return;
    }

    let tocEl = document.getElementById('toc');

    // Add an empty ToC div in case page doesn't have one.
    if (!tocEl) {
      const pageTitle = document.querySelector(
        'main > article > header[class^=PageHeader-module--pageHeader]'
      );
      tocEl = document.createElement('div');
      tocEl.classList.add('toc');

      pageTitle?.insertAdjacentElement('afterend', tocEl);
    }

    // Prepare banner container
    bannerWrapper = document.createElement('div');
    bannerWrapper.id = 'tocBanner';
    tocEl?.appendChild(bannerWrapper);

    // Banner elements
    const text = document.querySelector('.toc-banner-source-text')?.innerHTML;
    const link = document.querySelector('.toc-banner-source-link')?.textContent;

    const bannerHtml = `<div class='toc-banner'>
          <a href='${link}'>
            <div class="toc-banner--img"></div>
            <div class='toc-banner--content'>${text}</div>
          </a>
        </div>`;

    bannerWrapper.innerHTML = bannerHtml;

    // Add banner image
    const imgSource = document.querySelector('.toc-banner-source .image');
    const imgTarget = bannerWrapper.querySelector('.toc-banner--img');

    if (imgSource && imgTarget) {
      imgTarget.appendChild(imgSource);
    }
  }
}

44987B76-EADA-4279-85AB-C27CCC23B201

Docs