Form Binding Reference
The key concepts behind form binding are the field()
directive, the Model
, the Binder
and binder nodes.
The Field Directive
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 theerrorMessage
(string) when the current value is invalid.
import { TextField } from '@vaadin/react-components/TextField.js';
...
const { model, field } = useForm(PersonModel);
...
return (
<TextField label="Full name" {...field(model.fullName)} />
);
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.
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:
import { useForm, useFormPart } from '@vaadin/hilla-react-form';
import { StringModel } from '@vaadin/hilla-lit-form';
...
interface FullNameProps {
fullNameModel: StringModel;
}
function FullNameComponent({ fullNameModel }: FullNameProps) {
const { model, field, required, errors, invalid } = useFormPart(fullNameModel);
return (
<>
<label htmlFor="fullName">
Full name
{required ? '*' : ''}
</label>
<input id="fullName" {...field(model)}></input>
<br/>
<span className="label" style={{visibility: invalid ? 'visible' : 'hidden'}}>
<strong>
{errors[0]?.message}
</strong>
</span>
</>
);
}
export default function Main() {
const { model } = useForm(PersonModel);
return <FullNameComponent fullNameModel={model.fullName} />;
}
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
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) |
---|---|---|
|
|
|
|
|
|
|
|
|
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:
import { TextField } from '@vaadin/react-components/TextField.js';
interface PersonProps {
model: PersonModel;
}
function Person({ model }: PersonProps) {
const { field, model, value } = useFormPart(model);
return (
<div>
<TextField label="Full name" {...field(model.fullName)} />
<strong>Full name:</strong>
{value.fullName}
</div>
);
}
...
return (
<>
{model.people.map(person => <Person model={person} />)}
</>
);
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,
but, as we know that the model is just metadata, they cannot return any values. Then, those instance methods must be called on the value
property obtained from calling useForm
instead:
const { model, value } = useForm(PersonModel);
...
return (
<>
{value.name.toString()}
{value.name.valueOf()}
{value.name}
</>
)
Then, it’s possible to use the values in formulas using either of the following:
return (
<>
Cost: {value.quantity.valueOf() * value.price.valueOf()}
Cost: {value.quantity * value.price}
</>
);
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:
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;
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. TheBinder
extendsBinderNode
; 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.
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 thedefaultValue
. 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.