@@ -2585,12 +2585,59 @@ as it implies that it's possible to dispatch an event asynchronously.
|
2585 | 2585 | All events are dispatched synchronously. |
2586 | 2586 | What is more often implied by "asynchronous event" is to defer firing an event. |
2587 | 2587 | |
2588 | | -<h3 id="state-and-subclassing">Use plain {{Event}}s for state</h3> |
| 2588 | +<h3 id="state-and-subclassing">Put state on {{Event/target}} objects rather than {{Event}}s</h3> |
2589 | 2589 | |
2590 | | -Where possible, use a plain {{Event}} with a specified `type`, |
2591 | | -and capture any state information in the {{Event/target}} object. |
| 2590 | +Put state on the {{Event/target}} |
| 2591 | +and use events to signal updates to that state, |
| 2592 | +rather than having state on {{Event}} objects. |
2592 | 2593 | |
2593 | | -It's usually not necessary to create new subclasses of {{Event}}. |
| 2594 | +Having state on the {{Event/target}} object can used to determine the current state, |
| 2595 | +without waiting for the next event. |
| 2596 | +This is particularly useful if there's a final state, |
| 2597 | +where there will be no further events. |
| 2598 | + |
| 2599 | +It's usually not necessary to create new subclasses of {{Event}}, |
| 2600 | +but they can be used to provide information relating to how the state change occurred. |
| 2601 | + |
| 2602 | +<div class="example"> |
| 2603 | +Properties on {{HTMLInputElement}}, |
| 2604 | +such as {{HTMLInputElement/value}}, |
| 2605 | +provide the state of the input. |
| 2606 | +Properties on {{InputEvent}}, |
| 2607 | +such as {{InputEvent/inputType}}, |
| 2608 | +describe the nature of an update to the state. |
| 2609 | +</div> |
| 2610 | + |
| 2611 | +In some exceptional cases, where maintaining state on an object is expensive, |
| 2612 | +other patterns may be considered, |
| 2613 | +such as returning an {{EventTarget}} from a function call, |
| 2614 | +where the function call is a signal of interest. |
| 2615 | + |
| 2616 | +<div class="example"> |
| 2617 | + Using an imaginary `dataUsage` API that reports the amount of data an environment has used, the recommended pattern is: |
| 2618 | + |
| 2619 | +<pre highlight="js"> |
| 2620 | +self.dataUsage.addEventListener('change', () => { |
| 2621 | + console.log(self.dataUsage.bytesReceived); |
| 2622 | +}); |
| 2623 | +</pre> |
| 2624 | + |
| 2625 | + Where `bytesReceived` exists on the `dataUsage` {{EventTarget}}, |
| 2626 | + rather than the {{Event}}. |
| 2627 | + |
| 2628 | + If maintaining the state on this object is too expensive, this pattern may be considered: |
| 2629 | + |
| 2630 | +<pre highlight="js"> |
| 2631 | +const dataUsage = await self.monitorDataUsage(); |
| 2632 | + |
| 2633 | +dataUsage.addEventListener('change', () => { |
| 2634 | + console.log(dataUsage.bytesReceived); |
| 2635 | +}); |
| 2636 | +</pre> |
| 2637 | + |
| 2638 | + In this pattern, the call to `monitorDataUsage` signals interest in the data, |
| 2639 | + and the state does not need to be updated until `monitorDataUsage` is called. |
| 2640 | +</div> |
2594 | 2641 | |
2595 | 2642 | <h3 id="events-vs-observers">Use Events and Observers appropriately</h3> |
2596 | 2643 | |
|