docs(template-syntax): clarify [()] de-sugaring

also changed anchors to use id instead of name
This commit is contained in:
Ward Bell 2016-03-24 12:00:37 -07:00
parent a2cb80330a
commit 5af06f9f6a
1 changed files with 24 additions and 15 deletions

View File

@ -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 elements `src` property.
a id between enclosing square brackets identifies the target property. The target property in the following code is the image elements `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
Thats cumbersome. Who can remember what element property to set and what event reports user changes?
Thats 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 elements `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
Thats 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.
Thats 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" &lt;==> [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 &lt;template&gt;