The previous lesson ended with an honest problem: connectActions registers one handler for every button of every task, and as soon as you start creating the <li>s from JavaScript, the new elements will be born with no handler. The solution is not to reconnect everything each time, but to understand that an event does not happen on one element alone: it travels through the DOM tree, from the root down to the target and back. By taking advantage of that journey you can place a single handler on the container that attends to all of its children, present and future. In this lesson you will learn the three phases of that journey, the three ways of interrupting it (and how they differ), the delegation pattern —probably the highest-value technique in the whole module— and custom events, which will let the view and the model communicate without knowing each other.

1. The journey of an event: capture, target and bubbling
2. A demonstration on three levels
3. Listening in the capture phase
4. Stopping the journey: stopPropagation and stopImmediatePropagation
5. preventDefault is not the same thing (comparison table)
6. Events that do not bubble, and the equivalents that do
7. Event delegation
8. event.target.closest() and dataset: the complete pattern
9. Nómada Tasks: the board with a single handler
10. Custom events: CustomEvent and detail
11. Decoupling the view from the model with events
12. AbortController: removing many handlers at once
13. Common Mistakes and Tips
14. Exercises
15. Conclusion

When you click the button of a task, that click does not happen "on the button" and that is that. It happens on the button, which is inside an <li>, which is inside a <ul>, which is inside a <section>… The browser considers that the event concerns that whole chain, and it walks it in three phases:

1. Capture (capturing): the event descends from window down to the target element, passing through all of its ancestors.
2. Target: the event reaches the element where it actually happened.
3. Bubbling: the event rises from the target up to window, again through all of its ancestors.

By default, addEventListener registers the handler in the bubbling phase. That is why, in the previous lesson, a handler placed on the <li> fired when you clicked the button it contains: the event was born on the button and bubbled up to the <li>.

Two properties of the Event object describe this journey:

• event.eventPhase: 1 in capture, 2 at the target, 3 in bubbling.
• event.composedPath(): the complete array of nodes it passes through, from the target upward.

The best way to internalize this is to see it. Register a handler at each level and make a single click on the button:

A click on the button prints:

Four handlers executed with a single click. Fundamental observations:

• target is BUTTON in all four. The target does not change during the journey: it is always where the event happened. What changes is currentTarget, which on each line is the element where you registered that specific handler.
• No CAPTURE line appears, because the four handlers were registered in bubbling (the default value).
• The order is from the inside out. First the deepest one, then its ancestors.

This is exactly the property that makes delegation possible: a handler on the <ul> is already receiving the clicks of all its descendants.

With { capture: true } the handler is registered in the descending phase:

Now the same click prints:

Capture goes from the outside in and always happens before bubbling. There is also an inherited shorthand, addEventListener('click', fn, true), with the third parameter as a boolean; today the options object is preferred for readability.

When is capture used? Rarely, and always for a specific reason:

• To intercept before anybody else, for example to record analytics or to block interaction with a whole area of the interface while something is being saved.
• To capture events that do not bubble, such as focus or error on images, from a container. It is the trick in section 6.

In 95 % of cases, bubbling is what you want.

event.stopPropagation() stops the journey: the handlers still ahead in the tree do not run.

event.stopImmediatePropagation() is more forceful: as well as stopping the journey upward, it prevents the other handlers on the same element from running.

Important warning: stopPropagation is dangerous. It is a decision you take in one component and that affects the whole rest of the application, including the part you have not written yet. Typical scenario: you put stopPropagation on a card so that a click does not trigger something on the container; three weeks later somebody adds a handler on document to close a dropdown menu when clicking outside, and that menu stops closing on top of your cards. The failure is impossible to find because there is no error.

The alternative is almost always better: let the handler above check whether the event concerns it.

These three methods get confused constantly, and they do completely different things:

Practical corollary:

A useful detail: when a handler has called preventDefault(), later handlers on the journey can detect it with event.defaultPrevented, which lets you write cooperative code instead of code that steps on itself.

Not every event bubbles. The most important ones that do not:

A direct consequence: you cannot delegate focus or blur, because they never reach the container.

Option A is the recommended one: it is clearer and does not force you to reason about phases.

For load and error on images only capture is left, and it turns out to be very practical for detecting every broken image on the page in one go:

Delegation consists of registering a single handler on a common ancestor and deciding inside what to do depending on where the event came from. It takes advantage of the bubbling from section 1.

The three advantages, in order of importance:

1. It works with elements that do not exist yet. That is the main reason. When in 06-05 you create a new <li> and insert it into the <ul>, its clicks will bubble up to the handler that was already in place. Nothing has to be reconnected, and therefore there is no risk of duplicating handlers or of forgetting one.
2. Less memory and less registration work. One handler instead of two hundred. With six tasks the difference is irrelevant; with a long list, it is not. The question is dealt with in depth in Memory Management and Efficient DOM Manipulation.
3. A single place to read the interaction logic. The entire response to the list's clicks is in one function, not spread over six places.

It also has drawbacks worth knowing about: the handler receives all the clicks in the area, so it needs a clear guard at the start; and it does not work for events that do not bubble (section 6).

A delegated handler always has the same shape, and it is worth memorizing:

Every step has its reason:

• event.target is the deepest element, and that is the problem closest() solves. If your button contains a <span> with an icon, the target of a click on the icon will be the <span>, not the button. Checking event.target.matches('[data-action]') would fail in that case; closest() climbs until it finds the button and always works.
• The === null guard is mandatory. A click on the gap between two tasks also reaches your handler, and without the guard you would get a TypeError.
• dataset.action turns the handler into a generic dispatcher: there is no branch per button, but a piece of data in the HTML that says what to do. It is the lookup dictionary of 02-03 applied to the interface.
• Number(li.dataset.id) is the boundary conversion from 06-02: the page speaks in strings, the model in numbers.

We rewrite the controller from the previous lesson. Now the HTML includes two actions per task and uses data-action:

And the complete controller, with a single addEventListener:

Compare with the 06-03 version: there was an addEventListener inside a loop there; here there is a single one, outside every loop. And the important thing is what does not have to change when in the next lesson the <li>s are created from JavaScript: nothing. The handler is already on the <ul>, and any button that appears inside it will reach it by bubbling.

Until now every event came from the browser. But you can create and fire your own too, and that turns the DOM into a communication channel between the parts of your application.

Four important points:

• detail is the only place your data goes. It is a read-only property and it can hold any value: an object, an array, a number.
• bubbles is false by default, the opposite of most native events. If you forget it, the document handler never finds out and you will spend a good while looking for the failure.
• dispatchEvent is synchronous. It queues nothing: it runs the handlers immediately and hands control back when they finish. That is different from the behavior of user events, which do go through the task queue (05-07).
• The naming convention domain:action (task:changed, board:updated, filter:applied) avoids collisions with native events present and future, and makes it obvious in the code what is being talked about.

If the event is cancelable, dispatchEvent returns false when some handler called preventDefault(). That lets an event act as a request for permission:

This is the valuable use. Without custom events, every part of the interface that has to react to a change must be known by whoever causes it:

With events, whoever causes the change only announces that it has happened, and whoever is interested subscribes:

The controller does not know how many listeners there are or what they do. Adding a fourth does not force it to change a single line. In Nómada Tasks:

A click on "Start" for the carpentry task now produces, in a cascade and without any piece knowing the others:

And on the screen: the <li> repainted, the summary updated and a new line in the activity log.

When to use custom events and when not to. They are ideal for communicating upward or sideways (a component reports that something happened, without knowing who is listening). They are not appropriate for one-to-one communication where a direct function call is clearer: if the controller needs the immediate result of something, call it. And beware of overusing them: an application where everything communicates through events is hard to follow, because the trace stops reading top to bottom. A handful of well-named events is an architecture; thirty are a maze.

Remember the problem from 06-03: to remove a handler you need the exact reference of the function. With ten handlers scattered around, the cleanup becomes ten lines and ten variables.

AbortController solves it. It is an object with a signal property and an abort() method. If you pass that signal as an option to addEventListener, every handler registered with it is removed when abort() is called:

This fits perfectly with the lesson's pattern: each connectX function accepts a signal and passes it along, so that tearing down the entire interface is trivial.

Details worth knowing:

• An aborted signal cannot be reused: you have to create a new AbortController. If you register a handler with an already aborted signal, it simply is not registered.
• signal and once combine without any problem: { once: true, signal }.
• AbortController is not exclusive to events: it is the browser's standard cancellation mechanism, and you will use it again to cancel network requests in Robust Requests.

• Using event.target where closest() was needed. If the button contains an icon, target will be the icon. event.target.closest('[data-action]') is the correct pattern, always.
• Forgetting the guard if (element === null) return; in a delegated handler. You receive every click in the container, including the ones going nowhere, and without the guard you get a TypeError.
• Forgetting bubbles: true on a CustomEvent. The event fires, nothing fails and nobody hears it. It is the most baffling failure of the lesson, because there is no symptom.
• Overusing stopPropagation(). It breaks features that do not even exist yet and leaves no trace. Prefer a guard in the handler above.
• Believing preventDefault() stops bubbling. It does not, and stopPropagation() does not cancel the default action. They are independent axes: go back over the table in section 5.
• Trying to delegate focus or blur. They do not bubble. Use focusin/focusout, or register with { capture: true }.
• Delegating on document when the container was enough. The closer the handler is to the target, the fewer irrelevant events it has to discard. Delegate on the <ul>, not on document.
• Reusing an already aborted AbortController. It does not work again. Create a new one every time you mount the interface.
• Tip: name your events with domain:action. It avoids collisions and documents the intent. And centralize the strings in an EVENTS module, as in section 11, so that a typo is a visible undefined and not an event nobody listens to.
• Tip: use getEventListeners($0) in the Chrome console. It shows every handler on the selected element; it is the best way of verifying that delegation did not leave duplicated handlers along the way.

Register six click handlers —capture and bubbling on section, ul and li— and click the button of a task. Predict the order in writing before running it, then check it. Afterwards add stopPropagation() in the <ul>'s capture handler and explain exactly which handlers stop running and why.

Extend the delegated handler on #task-list so that it supports a third action, data-action="archive", which hides the <li> with hidden. Before archiving it must emit a cancelable task:before-archive event, and only carry on if nobody has vetoed it. Then write a listener that vetoes archiving any task that is not done. All of it with a single addEventListener on the <ul> (plus the veto listener).

Create js/view/workload.js with a function connectWorkload(container, board, { signal }) that draws the open hours per assignee (Iván 25, Lucía 14, Marta 6) and updates itself every time task:changed is emitted, without the board controller having to know this panel exists. Use AbortController in app.js so you can disconnect everything from the console.

Exercise 1

Order when clicking the button:

First the complete descent (from the outside in), then the complete climb (from the inside out). The <li> appears in both lists because it has a handler in each phase; since the real target is the <button>, for the <li> both are ordinary journey phases.

With stopPropagation() in the <ul>'s capture handler, the output shrinks to:

Everything else is cut off: the event does not even reach the <li>, nor the <button> (which was the target), nor does it climb back up. It is the most forceful demonstration of why stopPropagation in capture is so destructive: it cancels the event for the whole subtree, including the element where the user actually clicked.

Exercise 2

Two key points. The first: dispatchEvent returns false if some handler called preventDefault(), and that only works if the event was created with cancelable: true; without that option, preventDefault() is ignored and dispatchEvent always returns true. The second: the controller does not contain the rule "only what is done can be archived". That rule lives in another module, and could be changed or withdrawn without touching the controller. It is exactly the decoupling we are after.

Exercise 3

The panel starts with Iván: 25 h (56 %), Lucía: 14 h (31 %), Marta: 6 h (13 %), adding up to the canonical 45 open h. When the carpentry task is marked as done, Iván drops to 20 h and all the percentages recompute by themselves, without controller.js mentioning this module even once: the communication goes entirely through the task:changed event. And by running disconnect() in the console, the abort() removes both the board's delegated handler and the workload panel's in one go. The createElement, append and replaceChildren methods appearing here are exactly the topic of the next lesson.

You now know how an event travels and how to take advantage of it. The journey has three phases —capture from the outside in, target, and bubbling from the inside out—, addEventListener registers in bubbling unless you ask for { capture: true }, and throughout the trip target does not change (it is where the event happened) while currentTarget is different in each handler. You can interrupt the journey with stopPropagation() and, more forcefully, with stopImmediatePropagation(), which also cancels the other handlers on the same element; and you know that neither of the two is the same as preventDefault(), which cancels the browser's default action and does not touch propagation. You also know that stopPropagation is a decision with global consequences and that a guard in the handler above is almost always preferable. You know the events that do not bubble —focus, blur, load, error, mouseenter— and their alternatives: focusin/focusout or the capture phase.

On that basis you have the highest-value pattern of the module: delegation. A single handler on ul#task-list that attends to the clicks of every button of every task, with the canonical four-step shape: event.target.closest('[data-action]'), a guard against null, closest('li[data-id]') to know which task it is about, and Number(li.dataset.id) to cross the boundary into the model. It works with elements that do not exist yet —which is the main reason for using it and what will keep the next lesson from breaking anything—, consumes a fraction of the memory and concentrates all the interaction logic in one place.

And you have the mechanism for the pieces of the application to talk to each other without knowing each other: custom events. new CustomEvent('task:changed', { bubbles: true, detail }) and dispatchEvent, with the domain:action convention, the reminder that bubbles is false by default and that firing is synchronous, and the option of creating cancelable events that work as a request for permission. With them, the board controller limits itself to announcing what has happened, and the summary, the activity log and the workload panel per assignee —25 h for Iván, 14 for Lucía, 6 for Marta— update by themselves. AbortController rounds off the set: a shared signal that lets you remove at a stroke every handler registered with it, the same cancellation mechanism that will reappear with network requests in Module 7.

One big and very visible gap remains: the list still has a few <li>s written by hand in the HTML, while the backlog has six tasks and in 06-07 you will be able to add more. The page cannot go on being a fixed mold that we fill in; it has to be built from the model. How an element is created from scratch, how it is inserted in exactly the right place, how it is removed without leaving memory leaks, how a hundred nodes are inserted without punishing the browser and how a template declared in the HTML is cloned is Creating and Removing DOM Elements, where you will write view/card.js and finally turn a model Task into its complete <li>.