diff --git a/aio/content/guide/two-way-binding.en.md b/aio/content/guide/two-way-binding.en.md new file mode 100644 index 00000000000000..a824130c70fdd3 --- /dev/null +++ b/aio/content/guide/two-way-binding.en.md @@ -0,0 +1,76 @@ +# Two-way binding `[(...)]` + +Two-way binding gives your app a way to share data between a component class and +its template. + +
+ +See the for a working example containing the code snippets in this guide. + +
+ +## Basics of two-way binding + +Two-way binding does two things: + +1. Sets a specific element property. +1. Listens for an element change event. + +Angular offers a special _two-way data binding_ syntax for this purpose, `[()]`. +The `[()]` syntax combines the brackets +of property binding, `[]`, with the parentheses of event binding, `()`. + +
+ +
+ [( )] = banana in a box +
+ +Visualize a *banana in a box* to remember that the parentheses go _inside_ the brackets. + +
+ +The `[()]` syntax is easy to demonstrate when the element has a settable +property called `x` and a corresponding event named `xChange`. +Here's a `SizerComponent` that fits this pattern. +It has a `size` value property and a companion `sizeChange` event: + + + + + +The initial `size` is an input value from a property binding. +Clicking the buttons increases or decreases the `size`, within +min/max value constraints, +and then raises, or emits, the `sizeChange` event with the adjusted size. + +Here's an example in which the `AppComponent.fontSizePx` is two-way bound to the `SizerComponent`: + + + +The `AppComponent.fontSizePx` establishes the initial `SizerComponent.size` value. + + + +Clicking the buttons updates the `AppComponent.fontSizePx` via the two-way binding. +The revised `AppComponent.fontSizePx` value flows through to the _style_ binding, +making the displayed text bigger or smaller. + +The two-way binding syntax is really just syntactic sugar for a _property_ binding and an _event_ binding. +Angular desugars the `SizerComponent` binding into this: + + + +The `$event` variable contains the payload of the `SizerComponent.sizeChange` event. +Angular assigns the `$event` value to the `AppComponent.fontSizePx` when the user clicks the buttons. + +## Two-way binding in forms + +The two-way binding syntax is a great convenience compared to +separate property and event bindings. It would be convenient to +use two-way binding with HTML form elements like `` and +`` and -`` y +`