Explain event handlers and capturing

[timeowilliams]

Summary

Added statement about how the capture process within event lifecycles is optional.

Motivation

To allow readers of the documentation get a better grasp of the three stages and what is/not optional.

Supporting details

https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#bubbling_and_capturing_explained https://github.com/mdn/content/issues/13749

Related issues

Fixes #13749

Metadata

• [ ] Adds a new document
• [X] Rewrites (or significantly expands) a document
• [ ] Fixes a typo, bug, or other error

[github-actions[bot]]

Preview URLs

• https://pr13877.content.dev.mdn.mozit.cloud/en-US/docs/Learn/JavaScript/Building_blocks/Events

Flaws

URL: /en-US/docs/Learn/JavaScript/Building_blocks/Events Title: Introduction to events on GitHub Flaw count: 1

• broken_links:
  • Can't resolve https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener

External URLs

URL: /en-US/docs/Learn/JavaScript/Building_blocks/Events Title: Introduction to events on GitHub

• https://mdn.github.io/learning-area/javascript/building-blocks/events/preventdefault-validation.html (1 time) (Note! This may be a new URL 👀)
• https://mdn.github.io/learning-area/javascript/building-blocks/events/random-color-addeventlistener.html (1 time) (Note! This may be a new URL 👀)
• https://mdn.github.io/learning-area/javascript/building-blocks/events/random-color-eventobject.html (1 time) (Note! This may be a new URL 👀)
• https://mdn.github.io/learning-area/javascript/building-blocks/events/show-video-box-fixed.html (1 time) (Note! This may be a new URL 👀)
• https://mdn.github.io/learning-area/javascript/building-blocks/events/show-video-box.html (1 time) (Note! This may be a new URL 👀)
• https://mdn.github.io/learning-area/javascript/building-blocks/events/useful-eventtarget.html (1 time) (Note! This may be a new URL 👀)

(this comment was updated 2022-03-26 07:06:30.971606)

[teoli2003]

@Ondevai, can you review this?

[wbamberg]

Thanks for the update!

This section:

In modern browsers, by default, all event handlers are registered for the bubbling phase. So in our current example, when you select the video, the event bubbles from the

• It finds the click handler on the video element and runs it, so the video first starts playing.
• It then finds the click handler on the videoBox element and runs that, so the video is hidden as well.

...is talking about the bubbling phase. By splicing stuff about capturing in, it doesn't make sense any more.

I think the part about enabling capturing should go after this, like:

In modern browsers, by default, all event handlers are registered for the bubbling phase. So in our current example, when you select the video, the event bubbles from the

• It finds the click handler on the video element and runs it, so the video first starts playing.
• It then finds the click handler on the videoBox element and runs that, so the video is hidden as well.

In modern browsers, by default, event handlers are not registered for the capturing phase. To register an event handler for the capturing phase, instead of the bubbling phase, pass the useCapture argument or the capture option to addEventListener().

Also, when your edit says "*Generally when event handlers are added to HTML code" - what work is "Generally" doing here? Usually when I see this word I think it means "usually but not always", and in documentation this makes me think, "when isn't it?" and if the documentation doesn't go on to explain that case, then I am left confused.

[sideshowbarker]

@timeowilliams This seems to be waiting on your response to https://github.com/mdn/content/pull/13877#issuecomment-1079742220

[wbamberg]

Closing in favour of https://github.com/mdn/content/pull/20013.