Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add reference.adoc - PR 2733 #3155

Merged
merged 4 commits into from
Feb 6, 2024
Merged

Add reference.adoc - PR 2733 #3155

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6ad29ab
First pass at editing.
russelljtdyer Jan 29, 2024
473a41a
Second pass at editing.
russelljtdyer Jan 29, 2024
4d536b1
Merge branch 'next' into russell/add-reference-adoc-pr2733
russelljtdyer Jan 29, 2024
b2b5c49
Merge branch 'next' into russell/add-reference-adoc-pr2733
russelljtdyer Jan 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 24 additions & 19 deletions articles/hilla/lit/guides/forms/reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description: Understanding form binding.

// tag::content[]

The key concepts behind form binding are: the [methodname]`field()` directive, the [classname]`Model`, the [classname]`Binder` and binder nodes.
The key concepts behind form binding are the [methodname]`field()` directive, the [classname]`Model`, the [classname]`Binder` and binder nodes.


== The Field Directive
Expand All @@ -18,15 +18,15 @@ ifdef::hilla-lit[]
Form binding in Hilla works together with the Lit web component library and its underlying template rendering library, `lit-html`.
endif::hilla-lit[]

The [methodname]`field()` directive does the main task of binding the form field components in the template:
The [methodname]`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.

ifdef::hilla-react[]
.Using the field directive
.Using the Field Directive
[source,tsx]
----
import {TextField} from "@vaadin/react-components/TextField.js";
Expand All @@ -38,8 +38,9 @@ return (
);
----
endif::hilla-react[]

ifdef::hilla-lit[]
.Using the field directive
.Using the Field Directive
[source,html]
----
<vaadin-text-field
Expand All @@ -53,10 +54,10 @@ Depending on the type of the bound component, the field directive selects a stra

ifdef::hilla-lit[]
[NOTE]
You can find more information on field strategy customization in the <<{articles}/hilla/lit/guides/forms/web-component-field-strategy#, Using a Web Component Field>> article.
You can find more information on field strategy customization on the <<{articles}/hilla/lit/guides/forms/web-component-field-strategy#, Using a Web Component Field>> page.
endif::hilla-lit[]

The field directive supports Vaadin components and HTML input elements. Vaadin components have support for all 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 bind these manually in the template:
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:

ifdef::hilla-react[]
[source,tsx]
Expand Down Expand Up @@ -114,8 +115,8 @@ ${
----
endif::hilla-lit[]

[NOTE]
See also: <<{articles}/hilla/lit/guides/forms/vaadin-components#, Binding Data to Hilla Components>>
See the <<{articles}/hilla/lit/guides/forms/vaadin-components#, Binding Data to Hilla Components>> for more, related information.



== The Form Model
Expand All @@ -130,27 +131,25 @@ to specify the target form property to create a binding or to access the state.

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 [classname]`Binder` itself (for example, the form data object).
Technically, every model instance represents either a key of a parent model, or the value of the [classname]`Binder` itself (e.g., the form data object).

[NOTE]
====
The model classes aren't intended to be instantiated manually. Instead, the [classname]`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 ([methodname]`Model.createEmptyValue()` result)
| Type | Value type `T` | Empty Value ([methodname]`Model.createEmptyValue()` result)

| [classname]`StringModel` | `string` | `''`
| [classname]`NumberModel` | `number` | `0`
| [classname]`BooleanModel` | `boolean` | `false`
|===

Primitive models extend [classname]`PrimitiveModel<T>`. Primitive models are leaf nodes of the data structure; that is, they don't have nested field keys.
Primitive models extend [classname]`PrimitiveModel<T>`. Primitive models are leaf nodes of the data structure; they don't have nested field keys.


=== Object Models
Expand Down Expand Up @@ -243,13 +242,12 @@ export default class PersonModel<T extends Person = Person> extends IdEntityMode
----

[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 [methodname]`toString()` and [methodname]`valueOf()` methods inherited from [classname]`AbstractModel<T>` (see following).
====

The properties of object models are intentionally read-only.

=== The Array Model

=== Array Model

[classname]`ArrayModel<T>` is used to represent array properties.

Expand Down Expand Up @@ -306,12 +304,12 @@ endif::hilla-lit[]
The array entries aren't available for indexing with bracket notation (`[]`).


=== The Abstract Model Superclass
=== Abstract Model Superclass

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


==== The Empty Value Definition
==== Empty Value Definition

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

Expand Down Expand Up @@ -350,7 +348,7 @@ return (
)
----

Then, it is possible to use the values in formulas using either of the followings:
Then, it's possible to use the values in formulas using either of the following:

[source,tsx]
----
Expand Down Expand Up @@ -432,6 +430,7 @@ Sets the form to empty value, as defined in the Model.
Determines and returns the `field` directive strategy for the bound element. Override to customize the binding strategy for a component. The [classname]`Binder` extends [classname]`BinderNode`; see the inherited properties and methods that follow.



== Binder Nodes [[binder-node]]

The [classname]`BinderNode<T, M>` class provides the form-binding-related APIs with respect to a particular model instance.
Expand Down Expand Up @@ -490,3 +489,9 @@ A helper method for array modes, similar to [methodname]`appendItem()`, but prep
A helper method for array item models. If the node's **parent model** is an [classname]`ArrayModel<T>`, removes the item the array; otherwise throws an exception.

// end::content[]

++++
<style>
[class^=PageHeader-module--descriptionContainer] {display: none;}
</style>
++++
Loading