docs(template-syntax): clarify [()] de-sugaring
also changed anchors to use id instead of name
This commit is contained in:
parent
a2cb80330a
commit
5af06f9f6a
|
@ -542,7 +542,7 @@ table
|
|||
// #docregion property-binding-7
|
||||
:marked
|
||||
### Binding target
|
||||
A name between enclosing square brackets identifies the target property. The target property in the following code is the image element’s `src` property.
|
||||
a id between enclosing square brackets identifies the target property. The target property in the following code is the image element’s `src` property.
|
||||
|
||||
// #enddocregion property-binding-7
|
||||
+makeExample('template-syntax/ts/app/app.component.html', 'property-binding-1')(format=".")
|
||||
|
@ -901,7 +901,7 @@ code-example(format="", language="html").
|
|||
// #docregion ngModel-1
|
||||
.l-main-section
|
||||
:marked
|
||||
<a name="ngModel"></a>
|
||||
<a id="ngModel"></a>
|
||||
## Two-way binding with NgModel
|
||||
When developing data entry forms, we often want to both display a data property and update that property when the user makes changes.
|
||||
|
||||
|
@ -929,15 +929,22 @@ code-example(format="", language="html").
|
|||
+makeExample('template-syntax/ts/app/app.component.html', 'without-NgModel')(format=".")
|
||||
// #docregion ngModel-4
|
||||
:marked
|
||||
That’s cumbersome. Who can remember what element property to set and what event reports user changes?
|
||||
That’s cumbersome. Who can remember which element property to set and what event reports user changes?
|
||||
How do we extract the currently displayed text from the input box so we can update the data property?
|
||||
Who wants to look that up each time?
|
||||
|
||||
That `ngModel` directive hides these onerous details. It wraps the element’s `value` property, listens to the `input` event,
|
||||
and raises its own event with the changed text ready for us to consume.
|
||||
That `ngModel` directive hides these onerous details behind its own `ngModel` input and `ngModelChange` output properties.
|
||||
// #enddocregion ngModel-4
|
||||
+makeExample('template-syntax/ts/app/app.component.html', 'NgModel-3')(format=".")
|
||||
// #docregion ngModel-5
|
||||
.l-sub-section
|
||||
:marked
|
||||
The `ngModel` input property sets the element's value property and the `ngModelChange` output property
|
||||
listens for changes to the element's value.
|
||||
The details are specific to each kind of element and therefore the `NgModel` directive only works for elements
|
||||
that implement one of a few patterns such as the input box's `value` property and `change` event.
|
||||
We can't simply apply `[(ngModel)]` to our custom components unless we write them to conform.
|
||||
|
||||
:marked
|
||||
That’s an improvement, but it could be better.
|
||||
|
||||
|
@ -949,16 +956,18 @@ code-example(format="", language="html").
|
|||
// #docregion ngModel-6
|
||||
.l-sub-section
|
||||
:marked
|
||||
Internally, Angular maps the term `ngModel` to an `ngModel` input property and an
|
||||
`ngModelChange` output property.
|
||||
That’s a specific example of a more general pattern in which Angular matches `[(x)]` to an `x` input property
|
||||
for property binding and an `xChange` output property for event binding.
|
||||
`[(ngModel)]` is a specific example of a more general pattern in which Angular "de-sugars" the `[(x)]` syntax
|
||||
into an `x` input property for property binding and an `xChange` output property for event binding.
|
||||
Angular constructs the event property binding's template statement by appending `=$event`
|
||||
to the literal string of the template expression.
|
||||
code-example(format="." ).
|
||||
[(x)]="hero.name" <==> [x]="hero.name" (xChange)="hero.name=$event"
|
||||
|
||||
:marked
|
||||
Is `[(ngModel)]` all we need? Is there ever a reason to fall back to its expanded form?
|
||||
|
||||
Well, `NgModel` can only set the target property.
|
||||
What if we need to do something more or something different when the user changes the value?
|
||||
Then we need to use the expanded form.
|
||||
The `[( )]` syntax can only set the data-bound property when the value changes.
|
||||
If we need to do something more or something different, we need to write the expanded form ourselves.
|
||||
|
||||
Let's try something silly like forcing the input value to uppercase:
|
||||
// #enddocregion ngModel-6
|
||||
|
@ -973,7 +982,7 @@ figure.image-display
|
|||
// #docregion directives-1
|
||||
.l-main-section
|
||||
:marked
|
||||
<a name="directives"></a>
|
||||
<a id="directives"></a>
|
||||
## Built-in directives
|
||||
|
||||
Earlier versions of Angular included over seventy built-in directives.
|
||||
|
@ -1249,8 +1258,8 @@ figure.image-display
|
|||
// #enddocregion directives-ngForTrackBy-3
|
||||
|
||||
// #docregion star-template
|
||||
<a name="star-template"></a>
|
||||
<a name="structural-directive"></a>
|
||||
<a id="star-template"></a>
|
||||
<a id="structural-directive"></a>
|
||||
.l-main-section
|
||||
:marked
|
||||
## * and <template>
|
||||
|
|
Loading…
Reference in New Issue