From 177d76533d3bf246081d8e0061dbf6064277c778 Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Fri, 18 Sep 2020 16:43:40 -0400 Subject: [PATCH] docs: edit event-binding doc copy and headers (#38903) PR Close #38903 --- .pullapprove.yml | 1 + aio/content/guide/event-binding-concepts.md | 31 ++++++ aio/content/guide/event-binding.md | 116 +++++++------------- aio/content/navigation.json | 5 + 4 files changed, 74 insertions(+), 79 deletions(-) create mode 100644 aio/content/guide/event-binding-concepts.md diff --git a/.pullapprove.yml b/.pullapprove.yml index 9e6fa7ff9d..7e9c8a20aa 100644 --- a/.pullapprove.yml +++ b/.pullapprove.yml @@ -371,6 +371,7 @@ groups: 'aio/content/guide/built-in-template-functions.md', 'aio/content/examples/built-in-template-functions/**', 'aio/content/guide/event-binding.md', + 'aio/content/guide/event-binding-concepts.md', 'aio/content/examples/event-binding/**', 'aio/content/guide/interpolation.md', 'aio/content/examples/interpolation/**', diff --git a/aio/content/guide/event-binding-concepts.md b/aio/content/guide/event-binding-concepts.md new file mode 100644 index 0000000000..e040392a9d --- /dev/null +++ b/aio/content/guide/event-binding-concepts.md @@ -0,0 +1,31 @@ + +# How event binding works + +In an event binding, Angular configures an event handler for the target event. +You can use event binding with your own custom events. + +When the component or directive raises the event, the handler executes the template statement. +The template statement performs an action in response to the event. + +## Handling events + +A common way to handle events is to pass the event object, `$event`, to the method handling the event. +The `$event` object often contains information the method needs, such as a user's name or an image URL. + +The target event determines the shape of the `$event` object. +If the target event is a native DOM element event, then `$event` is a [DOM event object](https://developer.mozilla.org/en-US/docs/Web/Events), with properties such as `target` and `target.value`. + +In the following example the code sets the `` `value` property by binding to the `name` property. + + + + +With this example, the following actions occur: + +1. The code binds to the `input` event of the `` element, which allows the code to listen for changes. +1. When the user makes changes, the component raises the `input` event. +1. The binding executes the statement within a context that includes the DOM event object, `$event`. +1. Angular retrieves the changed text by following the path `$event.target.value` and updates the `name` property. + +If the event belongs to a directive or component, `$event` has the shape that the directive or component produces. + diff --git a/aio/content/guide/event-binding.md b/aio/content/guide/event-binding.md index dc17ec9b46..537c27d643 100644 --- a/aio/content/guide/event-binding.md +++ b/aio/content/guide/event-binding.md @@ -1,7 +1,6 @@ -# Event binding `(event)` +# Event binding -Event binding allows you to listen for certain events such as -keystrokes, mouse movements, clicks, and touches. +Event binding allows you to listen for and respond to user actions such as keystrokes, mouse movements, clicks, and touches.
@@ -9,100 +8,59 @@ See the for a working example containing the code
-Angular event binding syntax consists of a **target event** name -within parentheses on the left of an equal sign, and a quoted -template statement on the right. -The following event binding listens for the button's click events, calling -the component's `onSave()` method whenever a click occurs: +## Binding to events + +To bind to an event you use the Angular event binding syntax. +This syntax consists of a target event name within parentheses to the left of an equal sign, and a quoted template statement to the right. +In the following example, the target event name is `click` and the template statement is `onSave()`. + + +<button (click)="onSave()">Save<button> + + +The event binding listens for the button's click events and calls the component's `onSave()` method whenever a click occurs.
Syntax diagram
-## Target event - -As above, the target is the button's click event. - - - -Alternatively, use the `on-` prefix, known as the canonical form: - - - -Element events may be the more common targets, but Angular looks first to see if the name matches an event property -of a known directive, as it does in the following example: - - - -If the name fails to match an element event or an output property of a known directive, -Angular reports an “unknown directive” error. - -## *$event* and event handling statements - -In an event binding, Angular sets up an event handler for the target event. - -When the event is raised, the handler executes the template statement. -The template statement typically involves a receiver, which performs an action -in response to the event, such as storing a value from the HTML control -into a model. - -The binding conveys information about the event. This information can include data values such as an event object, string, or number named `$event`. - -The target event determines the shape of the `$event` object. -If the target event is a native DOM element event, then `$event` is a -[DOM event object](https://developer.mozilla.org/en-US/docs/Web/Events), -with properties such as `target` and `target.value`. - -Consider this example: - - - -This code sets the `` `value` property by binding to the `name` property. -To listen for changes to the value, the code binds to the `input` -event of the `` element. -When the user makes changes, the `input` event is raised, and the binding executes -the statement within a context that includes the DOM event object, `$event`. - -To update the `name` property, the changed text is retrieved by following the path `$event.target.value`. - -If the event belongs to a directive—recall that components -are directives—`$event` has whatever shape the directive produces. - ## Custom events with `EventEmitter` -Directives typically raise custom events with an Angular [EventEmitter](api/core/EventEmitter). -The directive creates an `EventEmitter` and exposes it as a property. -The directive calls `EventEmitter.emit(payload)` to fire an event, passing in a message payload, which can be anything. -Parent directives listen for the event by binding to this property and accessing the payload through the `$event` object. +[Directives](guide/built-in-directives) typically raise custom events with an Angular [EventEmitter](api/core/EventEmitter) as follows. + +1. The directive creates an `EventEmitter` and exposes it as a property. +1. The directive then calls `EventEmitter.emit(data)` to emit an event, passing in message data, which can be anything. +1. Parent directives listen for the event by binding to this property and accessing the data through the `$event` object. Consider an `ItemDetailComponent` that presents item information and responds to user actions. -Although the `ItemDetailComponent` has a delete button, it doesn't know how to delete the hero. It can only raise an event reporting the user's delete request. +Although the `ItemDetailComponent` has a delete button, it doesn't contain the functionality to delete the hero. +It can only raise an event reporting the user's delete request. -Here are the pertinent excerpts from that `ItemDetailComponent`: +The component defines a `deleteRequest` property that returns an `EventEmitter`. +When the user clicks **Delete**, the component invokes the `delete()` method, telling the `EventEmitter` to emit an `Item` object. + -The component defines a `deleteRequest` property that returns an `EventEmitter`. -When the user clicks *delete*, the component invokes the `delete()` method, -telling the `EventEmitter` to emit an `Item` object. - -Now imagine a hosting parent component that binds to the `deleteRequest` event -of the `ItemDetailComponent`. +The hosting parent component binds to the `deleteRequest` event of the `ItemDetailComponent` as follows. -When the `deleteRequest` event fires, Angular calls the parent component's -`deleteItem()` method, passing the *item-to-delete* (emitted by `ItemDetail`) -in the `$event` variable. +When the `deleteRequest` event fires, Angular calls the parent component's `deleteItem()` method with the item. -## Template statements have side effects +### Determining an event target -Though [template expressions](guide/interpolation#template-expressions) shouldn't have [side effects](guide/property-binding-best-practices#avoid-side-effects), template -statements usually do. The `deleteItem()` method does have -a side effect: it deletes an item. +To determine an event target, Angular checks if the name of the target event matches an event property of a known directive. +In the following example, Angular checks to see if `myClick` is an event on the custom `ClickDirective`. -Deleting an item updates the model, and depending on your code, triggers -other changes including queries and saving to a remote server. -These changes propagate through the system and ultimately display in this and other views. + + +If the target event name, `myClick` fails to match an element event or an output property of `ClickDirective`, Angular reports an "unknown directive" error. + +
+ +## What's next + +For more information on how event binding works, see [How event binding works](guide/event-binding-concepts). diff --git a/aio/content/navigation.json b/aio/content/navigation.json index 09a706e651..e84c358512 100644 --- a/aio/content/navigation.json +++ b/aio/content/navigation.json @@ -777,6 +777,11 @@ "url": "guide/architecture-next-steps", "title": "Next Steps", "tooltip": "Beyond the basics." + }, + { + "url": "guide/event-binding-concepts", + "title": "How event binding works", + "tooltip": "About event binding." } ] },