From 8af32fcb1665c3717f87fb651c0205dda718e5ed Mon Sep 17 00:00:00 2001 From: Michael Ziluck Date: Thu, 29 Oct 2020 16:59:58 +0000 Subject: [PATCH] docs(forms): update ngModel documentation (#39481) This commit improves the ngModel docs, specifically: - clarifies purpose of the name attribute in ngModelOptions - clarifies on the interaction with a parent form or lack thereof - fix inconsistency with analogy for two-way binding - cleans up some typos and extra wordiness - clarifies language around common properties - adds missing preposition to commit message format origins PR Close #39481 --- CONTRIBUTING.md | 2 +- packages/forms/src/directives/ng_model.ts | 33 ++++++++++++----------- 2 files changed, 19 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 103a8ad5a6..af0dbe6b03 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -209,7 +209,7 @@ To ensure consistency throughout the source code, keep these rules in mind as yo ## Commit Message Format -*This specification is inspired and supersedes the [AngularJS commit message format][commit-message-format].* +*This specification is inspired by and supersedes the [AngularJS commit message format][commit-message-format].* We have very precise rules over how our Git commit messages must be formatted. This format leads to **easier to read commit history**. diff --git a/packages/forms/src/directives/ng_model.ts b/packages/forms/src/directives/ng_model.ts index 6cd329877b..db0b593505 100644 --- a/packages/forms/src/directives/ng_model.ts +++ b/packages/forms/src/directives/ng_model.ts @@ -35,12 +35,12 @@ export const formControlBinding: any = { * ``` * I.e. `ngModel` can export itself on the element and then be used in the template. * Normally, this would result in expressions before the `input` that use the exported directive - * to have and old value as they have been + * to have an old value as they have been * dirty checked before. As this is a very common case for `ngModel`, we added this second change * detection run. * * Notes: - * - this is just one extra run no matter how many `ngModel` have been changed. + * - this is just one extra run no matter how many `ngModel`s have been changed. * - this is a general problem when using `exportAs` for directives! */ const resolvedPromise = (() => Promise.resolve(null))(); @@ -59,16 +59,17 @@ const resolvedPromise = (() => Promise.resolve(null))(); * `ngModel` selector to activate it. * * It accepts a domain model as an optional `Input`. If you have a one-way binding - * to `ngModel` with `[]` syntax, changing the value of the domain model in the component + * to `ngModel` with `[]` syntax, changing the domain model's value in the component * class sets the value in the view. If you have a two-way binding with `[()]` syntax - * (also known as 'banana-box syntax'), the value in the UI always syncs back to + * (also known as 'banana-in-a-box syntax'), the value in the UI always syncs back to * the domain model in your class. * - * To inspect the properties of the associated `FormControl` (like validity state), + * To inspect the properties of the associated `FormControl` (like the validity state), * export the directive into a local template variable using `ngModel` as the key (ex: - * `#myVar="ngModel"`). You then access the control using the directive's `control` property, but - * most properties used (like `valid` and `dirty`) fall through to the control anyway for direct - * access. See a full list of properties directly available in `AbstractControlDirective`. + * `#myVar="ngModel"`). You can then access the control using the directive's `control` property. + * However, the most commonly used properties (like `valid` and `dirty`) also exist on the control + * for direct access. See a full list of properties directly available in + * `AbstractControlDirective`. * * @see `RadioControlValueAccessor` * @see `SelectControlValueAccessor` @@ -112,15 +113,16 @@ const resolvedPromise = (() => Promise.resolve(null))(); * * ``` * - * ### Setting the ngModel name attribute through options + * ### Setting the ngModel `name` attribute through options * - * The following example shows you an alternate way to set the name attribute. The name attribute is - * used within a custom form component, and the name `@Input` property serves a different purpose. + * The following example shows you an alternate way to set the name attribute. Here, + * an attribute identified as name is used within a custom form control component. To still be able + * to specify the NgModel's name, you must specify it using the `ngModelOptions` input instead. * * ```html *
- * - * + * + * *
* * ``` @@ -156,7 +158,7 @@ export class NgModel extends NgControl implements OnChanges, OnDestroy { /** * @description - * Tracks the name bound to the directive. The parent form + * Tracks the name bound to the directive. If a parent form exists, it * uses this name as a key to retrieve this control's value. */ // TODO(issue/24571): remove '!'. @@ -184,7 +186,8 @@ export class NgModel extends NgControl implements OnChanges, OnDestroy { * as a standalone control. * * **standalone**: When set to true, the `ngModel` will not register itself with its parent form, - * and acts as if it's not in the form. Defaults to false. + * and acts as if it's not in the form. Defaults to false. If no parent form exists, this option + * has no effect. * * **updateOn**: Defines the event upon which the form control value and validity update. * Defaults to 'change'. Possible values: `'change'` | `'blur'` | `'submit'`.