diff --git a/articles/hilla/lit/guides/forms/reference.adoc b/articles/hilla/lit/guides/forms/reference.adoc index 5c78fb429e..813e72ccac 100644 --- a/articles/hilla/lit/guides/forms/reference.adoc +++ b/articles/hilla/lit/guides/forms/reference.adoc @@ -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 @@ -18,7 +18,7 @@ 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; @@ -26,7 +26,7 @@ The [methodname]`field()` directive does the main task of binding the form field - 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"; @@ -38,8 +38,9 @@ return ( ); ---- endif::hilla-react[] + ifdef::hilla-lit[] -.Using the field directive +.Using the Field Directive [source,html] ---- > 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] @@ -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 @@ -130,12 +131,10 @@ 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 @@ -143,14 +142,14 @@ The model classes aren't intended to be instantiated manually. Instead, the [cla 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`. Primitive models are leaf nodes of the data structure; that is, they don't have nested field keys. +Primitive models extend [classname]`PrimitiveModel`. Primitive models are leaf nodes of the data structure; they don't have nested field keys. === Object Models @@ -243,13 +242,12 @@ export default class PersonModel 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` (see following). -==== The properties of object models are intentionally read-only. -=== The Array Model + +=== Array Model [classname]`ArrayModel` is used to represent array properties. @@ -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` 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()`. @@ -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] ---- @@ -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` class provides the form-binding-related APIs with respect to a particular model instance. @@ -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`, removes the item the array; otherwise throws an exception. // end::content[] + +++++ + +++++ \ No newline at end of file