From 6ad29ab88596005f367489fda4eb417a38140e00 Mon Sep 17 00:00:00 2001 From: russelljtdyer <6652767+russelljtdyer@users.noreply.github.com> Date: Mon, 29 Jan 2024 15:33:08 +0100 Subject: [PATCH 1/2] First pass at editing. --- .../hilla/lit/guides/forms/reference.adoc | 88 +++++++++---------- 1 file changed, 43 insertions(+), 45 deletions(-) diff --git a/articles/hilla/lit/guides/forms/reference.adoc b/articles/hilla/lit/guides/forms/reference.adoc index 943b2830e0..68f1563ede 100644 --- a/articles/hilla/lit/guides/forms/reference.adoc +++ b/articles/hilla/lit/guides/forms/reference.adoc @@ -4,20 +4,21 @@ description: Understanding form binding. --- :hilla-lit: + = Form Binding Reference // 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 +== The Field Directive 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 job of binding the form field components in the template, namely: +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, @@ -25,7 +26,7 @@ The [methodname]`field()` directive does the main job 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"; @@ -37,8 +38,9 @@ return ( ); ---- endif::hilla-react[] + ifdef::hilla-lit[] -.Using the field directive +.Using the Field Directive [source,html] ---- > article. 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 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] @@ -116,53 +115,47 @@ ${ ---- 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 -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'`. +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 [methodname]`field()` directive ifdef::hilla-lit[] or the [methodname]`binder.for()` method endif::hilla-lit[] -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. +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 is usually no need to define models manually. +Hilla automatically generates Model classes for server-side endpoints from Java beans. Usually, there's 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. -==== +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`. -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 The primitive editable values of the form are typically grouped into objects. This is accommodated through [@classname]`ObjectModel`, which is also a common superclass for all the models generated from Java beans. -The subclasses of [classname]`ObjectModel` 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. +The subclasses of [classname]`ObjectModel` 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: @@ -201,7 +194,7 @@ public class Person extends IdEntity { } ---- -the following TypeScript interfaces are generated to type-check endpoints: +The following TypeScript interfaces are generated to type-check endpoints: .`IdEntity.ts` [source,typescript] @@ -221,7 +214,7 @@ export default interface Person extends IdEntity { } ---- -and the following models are generated for form binding: +The following models are generated for form binding: .`IdEntityModel.ts` [source,typescript] @@ -248,23 +241,20 @@ 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. 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. +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: +Array models are iterable. Iterating yields binder nodes for entries: ifdef::hilla-react[] [source,tsx] @@ -312,11 +302,13 @@ 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()`. @@ -328,12 +320,12 @@ const emptyPerson: Person = PersonModel.createEmptyValue(); console.log(emptyPerson); // {"fullName": ""} ---- + ==== Models in Expressions As with any JavaScript object, [classname]`AbstractModel` has [methodname]`toString(): string` and [methodname]`valueOf(): T` instance methods, ifdef::hilla-react[] -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 [classname]`useForm` instead: +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 [classname]`useForm` instead: endif::hilla-react[] ifdef::hilla-lit[] which are handy for template expressions. @@ -355,7 +347,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] ---- @@ -387,10 +379,10 @@ html` ---- endif::hilla-lit[] + == The Binder [[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. +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 [classname]`Binder` constructor arguments are: @@ -438,14 +430,14 @@ 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. 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 [classname]`BinderNode` instance. -The [classname]`Binder` itself is a [classname]`BinderNode` for the top-level form model. +Every model instance has a one-to-one mapping to a corresponding [classname]`BinderNode` instance. The [classname]`Binder` itself is a [classname]`BinderNode` for the top-level form model. ifdef::hilla-lit[] Use the [methodname]`binderNode.for()` method to obtain the binder node related to the model. endif::hilla-lit[] @@ -502,3 +494,9 @@ 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 From 473a41abf42bf3e1d64432c24b211ce98f17416a Mon Sep 17 00:00:00 2001 From: russelljtdyer <6652767+russelljtdyer@users.noreply.github.com> Date: Mon, 29 Jan 2024 15:47:45 +0100 Subject: [PATCH 2/2] Second pass at editing. --- articles/hilla/lit/guides/forms/reference.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/articles/hilla/lit/guides/forms/reference.adoc b/articles/hilla/lit/guides/forms/reference.adoc index 68f1563ede..60b6b75020 100644 --- a/articles/hilla/lit/guides/forms/reference.adoc +++ b/articles/hilla/lit/guides/forms/reference.adoc @@ -20,9 +20,9 @@ endif::hilla-lit[] 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, +- 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[] @@ -54,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 manually bind these 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]