Form Binding Reference

Understanding form binding.

The Field Directive
The Form Model
The Binder
Binder Nodes

The key concepts behind form binding are the field() directive, the Model, the Binder and binder nodes.

The Field Directive

Form binding in Hilla works together with the Lit web component library and its underlying template rendering library, lit-html.

The field() directive does the main task of binding the form field components in the template by doing the following:

sets the name attribute;
implements two-way binding for the value state;
sets the required (boolean) state; and
sets the invalid (boolean) state and the errorMessage (string) when the current value is invalid.

<vaadin-text-field
  label="Full name"
  ${field(model.fullName)}
></vaadin-text-field>

Depending on the type of the bound component, the field directive selects a strategy that defines exactly how the states above are applied on the component, for example which attributes and properties of the element are used.

Note	You can find more information on field strategy customization on the Using a Web Component Field page.

The field directive supports Vaadin components and HTML input elements. Vaadin components have support for all of the states. However, for HTML input elements, the invalid, required and errorMessage states aren’t displayed in the bound component. As a workaround, you can manually bind these in the template:

<label for="fullName">
  Full name
  ${binder.for(binder.model.fullName).required ? '*' : ''}
</label>
<input id="fullName" ${field(binder.model.fullName)} /><br/>
${
  binder.for(binder.model.fullName).invalid
    ? html`
      <strong>
        ${binder.for(binder.model.fullName).errors[0]}
      </strong>`
    : ''
}

See the Binding Data to Hilla Components for more, related information.

The Form Model

A form model describes the structure of the form. It allows individual fields to be referenced in a type-safe way, and is an alternative to strings such as 'person.firstName'.

Typically, a model is used as an argument for the field() directive or the binder.for() method to specify the target form property to create a binding or to access the state. In contrast to string names such as 'person.firstName', typed form models allow autocompletion and static type checking, which makes creating forms faster and safer.

Hilla automatically generates Model classes for server-side endpoints from Java beans. There’s usually no need to define models, manually.

Technically, every model instance represents either a key of a parent model, or the value of the Binder itself (e.g., the form data object).

Note	The model classes aren’t intended to be instantiated manually. Instead, the `Binder` constructor receives the form model class and takes care of creating model instances.

Primitive Models

These are the built-in models that represent the common primitive field types:

Type Value type T Empty Value (Model.createEmptyValue() result)

Type	Value type `T`	Empty Value (`Model.createEmptyValue()` result)
`StringModel`	`string`	`''`
`NumberModel`	`number`	`0`
`BooleanModel`	`boolean`	`false`

StringModel

string

''

NumberModel

number

0

BooleanModel

boolean

false

Primitive models extend PrimitiveModel<T>. Primitive models are leaf nodes of the data structure; they don’t have nested field keys.

Object Models

The primitive editable values of the form are typically grouped into objects. This is accommodated through ObjectModel<T>, which is also a common superclass for all the models generated from Java beans.

The subclasses of ObjectModel<T> define the type argument constraints and the default type. In addition, the subclasses list all the public properties, following the shape of the described object.

For example, for the following Java bean:

public class IdEntity {
    private String idString;

    public String getIdString() {
        return idString;
    }

    public void setIdString(String idString) {
        this.idString = idString;
    }
}

import jakarta.validation.constraints.NotEmpty;

public class Person extends IdEntity {
    @NotEmpty(message = "Cannot be empty")
    private String fullName;

    public String getFullName() {
        return fullName;
    }

    public void setFullName(String fullName) {
        this.fullName = fullName;
    }
}

The following TypeScript interfaces are generated to type-check endpoints:

export default interface IdEntity {
  idString: string | undefined;
}

import IdEntity from './IdEntity';

export default interface Person extends IdEntity {
  fullName: string | undefined;
}

The following models are generated for form binding:

import IdEntity from './IdEntity';

export default class IdEntityModel<T extends IdEntity = IdEntity> extends ObjectModel<T> {
  static createEmptyValue: () => IdEntity;
  readonly idString = new StringModel(this, 'idString');
}

import IdEntityModel from './IdEntityModel';

import Person from './Person';

export default class PersonModel<T extends Person = Person> extends IdEntityModel<T> {
  static createEmptyValue: () => Person;
  readonly fullName = new StringModel(this, 'fullName', new NotEmpty({message: 'Cannot be empty'}));
}

Caution

To avoid naming collisions with user-defined object model fields, the built-in models and model superclasses don’t have any public instance properties or methods, aside from the toString() and valueOf() methods inherited from AbstractModel<T> (see following).

The properties of object models are intentionally read-only.

Array Model

ArrayModel<T> is used to represent array properties.

The type argument T in array models indicates the type of values in the array.

An array model instance contains the item model class reference. The item model is instantiated for every array entry, as necessary.

Array models are iterable. Iterating yields binder nodes for entries:

${repeat(this.binder.model.people, personBinder => html`
  <div>
    <vaadin-text-field
      label="Full name"
      ${field(personBinder.model.fullName)}
    ></vaadin-text-field>
    <strong>Full name:</strong>
    ${personBinder.value.fullName}
  </div>
`)}

The array entries aren’t available for indexing with bracket notation ([]).

Abstract Model Superclass

All models subclass from the AbstractModel<T> TypeScript class, where the T type argument refers to the value type.

Empty Value Definition

Model classes define an empty value, which is used to initialize the defaultValue and value properties, and also for clear().

For this purpose, AbstractModel<T>, as well as every subclass, has a method static createEmptyValue(): T, which returns the empty value of the subject model type.

const emptyPerson: Person = PersonModel.createEmptyValue();
console.log(emptyPerson); // {"fullName": ""}

Models in Expressions

As with any JavaScript object, AbstractModel<T> has toString(): string and valueOf(): T instance methods, which are handy for template expressions.

For StringModel in string expressions, the following are equivalent:

html`
  ${model.fullName.toString()}
  ${model.fullName.valueOf()}
  ${model.fullName}
`;

You can use NumberModel in formulas using valueOf():

html`
  Cost: ${model.quantity.valueOf() * model.price.valueOf()}
`;

The Binder

A form binder controls all aspects of a single form. It’s typically used to get and set the form value, access the form model, validate, reset, and submit the form.

The Binder constructor arguments are:

context: Element

The form view component instance to update;

Model: ModelConstructor<T, M>

The constructor (class reference) of the form model. The Binder instantiates the top-level model; and

config?: BinderConfiguration<T>

The options object.

onChange?: (oldValue?: T) ⇒ void: The callback that updates the form view; by default, it uses context.requestUpdate().
onSubmit?: (value: T) ⇒ Promise<T | void>: The endpoint to submit the form data to.

The Binder has the following instance properties:

model: M: The form model, the top-level model instance created by the Binder.
value: T: The current value of the form, two-way bound to the field components.
defaultValue: T: The initial value of the form, before any fields are edited by the user.
readonly validating: boolean: True when there is an ongoing validation.
readonly submitting: boolean: True if the form was submitted, but the submit promise isn’t resolved yet.

The Binder instance methods are:

read(value: T): void: Load the given value to the form.
reset(): void: Reset the form to the previous value.
clear(): void: Sets the form to empty value, as defined in the Model.
getFieldStrategy(element: any): FieldStrategy: Determines and returns the field directive strategy for the bound element. Override to customize the binding strategy for a component. The Binder extends BinderNode; see the inherited properties and methods that follow.

Binder Nodes

The BinderNode<T, M> class provides the form-binding-related APIs with respect to a particular model instance.

Structurally, model instances form a tree in which the object and array models have child nodes of field and array item model instances.

Every model instance has a one-to-one mapping to a corresponding BinderNode instance. The Binder itself is a BinderNode for the top-level form model. Use the binderNode.for() method to obtain the binder node related to the model. The binder nodes have the following properties:

model: M: The model instance mapped to this binder node.
value: T: The current value related to the model, two-way bound to the field components.
readonly defaultValue: T: The default value related to the model. Note: this is read-only here; use the top-level binder.defaultValue to change.
parent: BinderNode<any, AbstractModel<any>> | undefined: The parent node, if this binder node corresponds to a nested model; otherwise, undefined for the top-level binder.
binder: Binder<any, AbstractModel<any>>: The binder for the top-level model.
readonly name: string: The name generated from the model structure, used to set the name attribute on the field components.
readonly required: boolean: True if the value is required to be non-empty. Based on the presence of validators that have the impliesRequired: true flag.
dirty: boolean: True if the current value is different from the defaultValue.
visited: boolean: True if the bound field was ever focused and blurred by the user. The value is set by the field directive.
validators: ReadonlyArray<Validator<T>>: The array of validators for the model. The default value is defined in the model.
readonly ownErrors: ReadonlyArray<ValueError<T>>: The array of validation errors directly related with the model.
readonly errors: ReadonlyArray<ValueError<any>>: The combined array of all errors for this node’s model and all its nested models.
readonly invalid: boolean: True when the errors array isn’t empty.

The binder node has the following instance methods:

for<NM extends AbstractModel<any>>(model: NM): BinderNode<ModelType<NM>, NM>: Returns a binder node for the nested model instance.
async validate(): Promise<ReadonlyArray<ValueError<any>>>: Runs all validation callbacks potentially affecting this or any nested model. Returns the combined array of all errors, as in the errors property.
addValidator(validator: Validator<T>): void: A helper method to add a validator to the validators.
appendItem(itemValue?: T): void: A helper method for array models. If the node’s model is an ArrayModel<T>, appends an item to the array; otherwise throws an exception. If the argument is given, the argument value is used for the new item; otherwise, a new empty item is created.
prependItem(itemValue?: T): void: A helper method for array modes, similar to appendItem(), but prepends an item to the array.
removeSelf(): void: A helper method for array item models. If the node’s parent model is an ArrayModel<T>, removes the item the array; otherwise throws an exception.

Docs