tutorial-binder.asciidoc

title	order	layout
Binding Data to Client-Side Forms	1	page

Binding Data to Client-Side Forms

Vaadin provides means for binding UI components in TypeScript form views.

The client-side Binder supports Java backend endpoints for loading and saving the form data, and reuses the metadata from Java Bean validation annotations for client-side validation.

API Basics

The client-side form binding API consists of three key concepts:

• The field() directive for binding the field components in LitElement form view templates

• The generated TypeScript models for POJO classes used in endpoints, that are used as field references and provide the necessary metadata

• The client-side Binder TypeScript class that is responsible for keeping track of the form state, the default and current values, and validation of the data.

Note	See the Appendix: Client-Side Form Binding Reference for more details.

How to Bind Form Data

For example, let us consider a Java endpoint with methods for loading and saving a Person bean:

/**
 * A Vaadin endpoint for the person-view.ts form view.
 */
@Endpoint
public class PersonEndpoint {
    /**
     * Loads a Person to edit into the view.
     * @return default form data
     */
    public Person loadPerson() {
        // ...
    }

    /**
     * Saves the edited Person from the view.
     * @param person form data to save
     */
    public void savePerson(Person person) {
        // ...
    }
}

To bind data to a form, follow these steps in your frontend/views/person/person-view.ts client-side LitElement view:

1. Import the Binder class, the field() template directive from the @vaadin/form package. Import your personEndpoint data endpoint and the generated PersonModel from the frontend/generated folder:

   import {Binder, field} from '@vaadin/form';
   
   import * as personEndpoint from '../../generated/PersonEndpoint';
   import PersonModel from '../../generated/com/example/application/PersonModel';

2. Create a Binder instance for your view using generated PersonModel:

   @customElement('person-form')
   class PersonForm extends LitElement {
     // ...
   
     private binder = new Binder(this, PersonModel);
   
     // ...
   }

   The PersonModel here is generated alongside with a Person TypeScript data interface from the Person.java bean. It describes the structure of the data and the validation-related metadata for the client-side form binding.

3. Bind the UI components in the template using the ...="${field()}" syntax:

   class PersonForm extends LitElement {
     // ...
   
     render() {
       return html`
         <vaadin-text-field
          label="Full name"
          ...="${field(this.binder.model.fullName)}"
         ></vaadin-text-field>
       `;
     }
   }

   In this example, this.binder.model is an instance of PersonModel.

   Note	Models do not contain any actual data. Use this.binder.value or this.binder.defaultValue to access the actual current or default value of the form respectively.