diff --git a/aio/content/guide/binding-syntax.md b/aio/content/guide/binding-syntax.md index d5f4747cdf..0511b536d1 100644 --- a/aio/content/guide/binding-syntax.md +++ b/aio/content/guide/binding-syntax.md @@ -1,11 +1,8 @@ -# Binding syntax: an overview +# Binding syntax -Data-binding is a mechanism for coordinating what users see, specifically -with application data values. -While you could push values to and pull values from HTML, -the application is easier to write, read, and maintain if you turn these tasks over to a binding framework. -You simply declare bindings between binding sources, target HTML elements, and let the framework do the rest. +Data binding automatically keeps your page up-to-date based on your application's state. +You use data binding to specify things such as the source of an image, the state of a button, or data for a particular user.
@@ -13,11 +10,107 @@ See the for a working example containing the code
-Angular provides many kinds of data-binding. Binding types can be grouped into three categories distinguished by the direction of data flow: -* From the _source-to-view_ -* From _view-to-source_ -* Two-way sequence: _view-to-source-to-view_ +## Data binding and HTML + +Developers can customize HTML by specifying attributes with string values. +In the following example, `class`, `src`, and `disabled` modify the `
`, ``, and ` +``` + +Use data binding to control things like the state of a button: + + + +Notice that the binding is to the `disabled` property of the button's DOM element, not the attribute. +Data binding works with properties of DOM elements, components, and directives, not HTML attributes. + +{@a html-attribute-vs-dom-property} + +### HTML attributes and DOM properties + +Angular binding distinguishes between HTML attributes and DOM properties. + +Attributes initialize DOM properties and you can configure them to modify an element's behavior. +Properties are features of DOM nodes. + +* A few HTML attributes have 1:1 mapping to properties; for example, `id`. + +* Some HTML attributes don't have corresponding properties; for example, `aria-*`. + +* Some DOM properties don't have corresponding attributes; for example, `textContent`. + +
+ +Remember that HTML attributes and DOM properties 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. + +When you write a data binding, you're dealing exclusively with the DOM properties and events of the target object. + +#### Example 1: an `` + +When the browser renders ``, it creates a +corresponding DOM node with a `value` property and initializes that `value` to "Sarah". + +```html + +``` + +When the user enters `Sally` into the ``, the DOM element `value` property becomes `Sally`. +However, if you look at the HTML attribute `value` using `input.getAttribute('value')`, you can see that the attribute remains unchanged—it returns "Sarah". + +The HTML attribute `value` specifies the initial value; the DOM `value` property is the current value. + +To see attributes versus DOM properties in a functioning app, see the especially for binding syntax. + +#### Example 2: a disabled button + +A button's `disabled` property is `false` by default so the button is enabled. + +When you add the `disabled` attribute, you are initializing the button's `disabled` property to `true` which disables the button. + +```html + +``` + +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 ``. + +To control the state of the button, set the `disabled` property instead. + +Property and attribute comparison + +Though you could technically set the `[attr.disabled]` attribute binding, the values are different in that the property binding must be a boolean value, while its corresponding attribute binding relies on whether the value is `null` or not. +Consider the following: + +```html + + +``` + +The first line, which uses the `disabled` property, uses a boolean value. +The second line, which uses the disabled attribute checks for `null`. + +Generally, use property binding over attribute binding as a boolean value is easy to read, the syntax is shorter, and a property is more performant. + +To see the `disabled` button example in a functioning application, see the . +This example shows you how to toggle the disabled property from the component. + + +## Types of data binding + +Angular provides three categories of data binding according to the direction of data flow: + +* From the source to view +* From view to source +* In a two way sequence of view to source to view