diff --git a/aio/content/guide/template-syntax.md b/aio/content/guide/template-syntax.md index 8c6ef988f3..622f937f89 100644 --- a/aio/content/guide/template-syntax.md +++ b/aio/content/guide/template-syntax.md @@ -6,8 +6,7 @@ h4 .syntax { font-size: 100%; } -The Angular application manages what the user sees and can do, achieving this through the interaction of a -component class instance (the *component*) and its user-facing template. +The Angular application manages what the user sees and can do, achieving this through the interaction of a component class instance (the *component*) and its user-facing template. You may be familiar with the component/template duality from your experience with model-view-controller (MVC) or model-view-viewmodel (MVVM). In Angular, the component plays the part of the controller/viewmodel, and the template represents the view. @@ -85,12 +84,10 @@ converts the expression results to strings, and links them with neighboring lite it assigns this composite interpolated result to an **element or directive property**. You appear to be inserting the result between element tags and assigning it to attributes. +However, interpolation is a special syntax that Angular converts into a *property binding*.
-However, interpolation is a special syntax that Angular converts into a -property binding. - If you'd like to use something other than `{{` and `}}`, you can configure the interpolation delimiter via the [interpolation](api/core/Component#interpolation) @@ -124,8 +121,8 @@ including: Other notable differences from JavaScript syntax include: * No support for the bitwise operators such as `|` and `&` -* New template expression operators, such as `|`, `?.` and `!` - +* New [template expression operators](guide/template-syntax#expression-operators), such as `|`, `?.` and `!` + ### Expression context @@ -171,12 +168,29 @@ members of the expression context. When using template expressions follow these guidelines: -* [No visible side effects](guide/template-syntax#no-visible-side-effects) -* [Quick execution](guide/template-syntax#quick-execution) * [Simplicity](guide/template-syntax#simplicity) +* [Quick execution](guide/template-syntax#quick-execution) +* [No visible side effects](guide/template-syntax#no-visible-side-effects) +#### Simplicity -### No visible side effects +Although it's possible to write complex template expressions, it's a better +practice to avoid them. + +A property name or method call should be the norm, but an occasional Boolean negation, `!`, is OK. +Otherwise, confine application and business logic to the component, +where it is easier to develop and test. + +#### Quick execution + +Angular executes template expressions after every change detection cycle. +Change detection cycles are triggered by many asynchronous activities such as +promise resolutions, HTTP results, timer events, key presses and mouse moves. + +Expressions should finish quickly or the user experience may drag, especially on slower devices. +Consider caching values when their computation is expensive. + +#### No visible side effects A template expression should not change any application state other than the value of the target property. @@ -187,40 +201,18 @@ The view should be stable throughout a single rendering pass. An [idempotent](https://en.wikipedia.org/wiki/Idempotence) expression is ideal because it is free of side effects and improves Angular's change detection performance. - In Angular terms, an idempotent expression always returns -*exactly the same thing* until -one of its dependent values changes. +*exactly the same thing* until one of its dependent values changes. Dependent values should not change during a single turn of the event loop. If an idempotent expression returns a string or a number, it returns the same string or number when called twice in a row. If the expression returns an object, including an `array`, it returns the same object *reference* when called twice in a row.
-There is one exception to this behavior that applies to `*ngFor`. `*ngFor` has `trackBy` functionality that can deal with referential inequality of objects that when iterating over them. - -For more information, see the [*ngFor with `trackBy`](guide/template-syntax#ngfor-with-trackby) section of this guide. +There is one exception to this behavior that applies to `*ngFor`. `*ngFor` has `trackBy` functionality that can deal with referential inequality of objects when iterating over them. See [*ngFor with `trackBy`](guide/template-syntax#ngfor-with-trackby) for details.
-### Quick execution - -Angular executes template expressions after every change detection cycle. -Change detection cycles are triggered by many asynchronous activities such as -promise resolutions, HTTP results, timer events, key presses and mouse moves. - -Expressions should finish quickly or the user experience may drag, especially on slower devices. -Consider caching values when their computation is expensive. - -### Simplicity - -Although it's possible to write complex template expressions, it's a better -practice to avoid them. - -A property name or method call should be the norm, but an occasional Boolean negation, `!`, is OK. -Otherwise, confine application and business logic to the component, -where it is easier to develop and test. -
@@ -278,19 +270,15 @@ Template context names take precedence over component context names. In `deleteHero(hero)` above, the `hero` is the template input variable, not the component's `hero` property. +### Statement guidelines + Template statements cannot refer to anything in the global namespace. They can't refer to `window` or `document`. They can't call `console.log` or `Math.max`. -### Statement guidelines - As with expressions, avoid writing complex template statements. A method call or simple property assignment should be the norm. -Now that you have a feel for template expressions and statements, -you're ready to learn about the varieties of data binding syntax beyond interpolation. - -
{@a binding-syntax} @@ -396,7 +384,7 @@ Every public member of a **source** directive is automatically available for bin You don't have to do anything special to access a directive member in a template expression or statement. -## Data-binding and HTML +### Data-binding and HTML In the normal course of HTML development, you create a visual structure with HTML elements, and you modify those elements by setting element attributes with string constants. @@ -415,10 +403,10 @@ Notice that the binding is to the `disabled` property of the button's DOM elemen **not** the attribute. This applies to data-binding in general. Data-binding works with *properties* of DOM elements, components, and directives, not HTML *attributes*. -## HTML attribute vs. DOM property +### HTML attribute vs. DOM property The distinction between an HTML attribute and a DOM property is key to understanding -how Angular binding works. **Attributes are defined by HTML. Properties are accessed from DOM, or the Document Object Model, nodes.** +how Angular binding works. **Attributes are defined by HTML. Properties are accessed from DOM (Document Object Model) nodes.** * A few HTML attributes have 1:1 mapping to properties; for example, `id`. @@ -426,31 +414,30 @@ how Angular binding works. **Attributes are defined by HTML. Properties are acce * Some DOM properties don't have corresponding attributes; for example, `textContent`. -This general rule can help you build a mental model of attributes and DOM properties: -**attributes initialize DOM properties and then they are done. -Property values can change; attribute values can't.** +It is important to remember that *HTML attribute* and the *DOM property* are different things, even when they have the same name. +In Angular, the only role of HTML attributes is to initialize element and directive state. + +**Template binding works with *properties* and *events*, not *attributes*.** + +When you write a data-binding, you're dealing exclusively with the *DOM properties* and *events* of the target object.
-There is, of course, an exception to this rule because attributes can be changed by `setAttribute()`, which will re-initialize corresponding DOM properties again. +This general rule can help you build a mental model of attributes and DOM properties: +**Attributes initialize DOM properties and then they are done. +Property values can change; attribute values can't.** + +There is one exception to this rule. +Attributes can be changed by `setAttribute()`, which re-initializes corresponding DOM properties.
-Comparing the [`` attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td) - attributes to the [`` properties](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableCellElement) - provides a helpful -example for differentiation. In particular, you can navigate from the attributes -page to the properties via "DOM interface" link, and navigate the inheritance -hierarchy up to `HTMLTableCellElement`. - -**The HTML attribute and the DOM property are not the same thing, even when they have the same name.** - For more information, see the [MDN Interfaces documentation](https://developer.mozilla.org/en-US/docs/Web/API#Interfaces) which has API docs for all the standard DOM elements and their properties. +Comparing the [`` attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td) attributes to the [`` properties](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableCellElement) provides a helpful example for differentiation. +In particular, you can navigate from the attributes page to the properties via "DOM interface" link, and navigate the inheritance hierarchy up to `HTMLTableCellElement`. - - -### Example 1: an `` +#### Example 1: an `` When the browser renders ``, it creates a corresponding DOM node with a `value` property initialized to "Sarah". @@ -466,7 +453,7 @@ The HTML attribute `value` specifies the *initial* value; the DOM `value` proper To see attributes versus DOM properties in a functioning app, see the especially for binding syntax. -### Example 2: a disabled button +#### Example 2: a disabled button The `disabled` attribute is another example. A button's `disabled` *property* is `false` by default so the button is enabled. @@ -479,8 +466,7 @@ so the button is disabled. ``` -Adding and removing the `disabled` *attribute* disables and -enables the button. +Adding and removing the `disabled` *attribute* disables and enables the button. However, the value of the *attribute* is irrelevant, which is why you cannot enable a button by writing ``. @@ -488,7 +474,7 @@ To control the state of the button, set the `disabled` *property*,
-**Note:** Though you could technically set the `[attr.disabled]` attribute binding, the values are different in that the property binding requires to a boolean value, while its corresponding attribute binding relies on whether the value is `null` or not. Consider the following: +Though you could technically set the `[attr.disabled]` attribute binding, the values are different in that the property binding requires to a boolean value, while its corresponding attribute binding relies on whether the value is `null` or not. Consider the following: ```html @@ -499,26 +485,15 @@ Generally, use property binding over attribute binding as it is more intuitive (
-**The HTML attribute and the DOM property are different things, even when they have the same name.** - -**Template binding works with *properties* and *events*, not *attributes*.** To see the `disabled` button example in a functioning app, see the especially for binding syntax. This example shows you how to toggle the disabled property from the component. - -### Angular and attributes - -In Angular, the only role of attributes is to initialize element and directive state. -When you write a data-binding, you're dealing exclusively with properties and events of the target object. - - -## Binding targets +## Binding types and targets The **target of a data-binding** is something in the DOM. -Depending on the binding type, the target can be a -property (element, component, or directive), an -event (element, component, or directive), or sometimes an attribute name. -The following table summarizes: +Depending on the binding type, the target can be a property (element, component, or directive), +an event (element, component, or directive), or sometimes an attribute name. +The following table summarizes the targets for the different binding types.