Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

Commit 041bcb3

Browse files
committed
docs(template-syntax): mention value accessors in ngModel
1 parent 5af06f9 commit 041bcb3

File tree

1 file changed

+14
-9
lines changed

1 file changed

+14
-9
lines changed

public/docs/ts/latest/guide/template-syntax.jade

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -905,7 +905,7 @@ code-example(format="", language="html").
905905
## Two-way binding with NgModel
906906
When developing data entry forms, we often want to both display a data property and update that property when the user makes changes.
907907

908-
The `NgModel` directive serves that purpose, as in this example:
908+
The `[(NgModel)]` two-way data binding syntax makes that easy. Here's an example:
909909
// #enddocregion ngModel-1
910910
+makeExample('template-syntax/ts/app/app.component.html', 'NgModel-1')(format=".")
911911
// #docregion ngModel-2
@@ -923,7 +923,8 @@ code-example(format="", language="html").
923923
:marked
924924
There’s a story behind this construction, a story that builds on the property and event binding techniques we learned previously.
925925

926-
We could have achieved the same result as `NgModel` with separate bindings to
926+
### Inside [(ngModel)]
927+
We could have achieved the same result with separate bindings to
927928
the `<input>` element's `value` property and `input` event.
928929
// #enddocregion ngModel-3
929930
+makeExample('template-syntax/ts/app/app.component.html', 'without-NgModel')(format=".")
@@ -941,14 +942,15 @@ code-example(format="", language="html").
941942
:marked
942943
The `ngModel` input property sets the element's value property and the `ngModelChange` output property
943944
listens for changes to the element's value.
944-
The details are specific to each kind of element and therefore the `NgModel` directive only works for elements
945-
that implement one of a few patterns such as the input box's `value` property and `change` event.
946-
We can't simply apply `[(ngModel)]` to our custom components unless we write them to conform.
945+
The details are specific to each kind of element and therefore the `NgModel` directive only works for elements,
946+
such as the input text box, that are supported by a [ControlValueAccessor](../api/common/ControlValueAccessor-interface.html).
947+
We can't apply `[(ngModel)]` to our custom components until we write a suitable *value accessor*,
948+
a technique that is out of scope for this chapter.
947949

948950
:marked
949-
That’s an improvement, but it could be better.
950-
951-
We shouldn't have to mention the data property twice. Angular should be able to read the component’s data property and set it
951+
Separate `ngModel` bindings is an improvement. We can do better.
952+
953+
We shouldn't have to mention the data property twice. Angular should be able to capture the component’s data property and set it
952954
with a single declaration &mdash; which it can with the `[( )]` syntax:
953955
// #enddocregion ngModel-5
954956
+makeExample('template-syntax/ts/app/app.component.html', 'NgModel-1')(format=".")
@@ -962,11 +964,14 @@ code-example(format="", language="html").
962964
to the literal string of the template expression.
963965
code-example(format="." ).
964966
[(x)]="hero.name" &lt;==> [x]="hero.name" (xChange)="hero.name=$event"
967+
968+
:marked
969+
We can write a two-way binding directive of our own to exploit this behavior.
965970

966971
:marked
967972
Is `[(ngModel)]` all we need? Is there ever a reason to fall back to its expanded form?
968973

969-
The `[( )]` syntax can only set the data-bound property when the value changes.
974+
The `[( )]` syntax can only _set_ a data-bound property.
970975
If we need to do something more or something different, we need to write the expanded form ourselves.
971976

972977
Let's try something silly like forcing the input value to uppercase:

0 commit comments

Comments
 (0)