MDN Web Docs
-
|
In openwebdocs/project#61 @foolip suggests we unify event and event handler pages (in MDN content and in BCD). Example for an event page: XRSession end event (event name to pass into The IDL for this is the following and the event is often announced in specs in the texts like "The [SecureContext, Exposed=Window] interface XRSession : EventTarget {
attribute EventHandler onend;
}Philip says:
I think it is a good idea. We need to agree on how such a unified event page should look like, though, and we need to define one data point in BCD. Currently there are two data points:
So what do you all think? Could there be a page: https://developer.mozilla.org/en-US/docs/Web/API/XRSession/end_event |
Beta Was this translation helpful? Give feedback.
Replies: 7 comments 15 replies
-
|
I'm pro having one page for simplicity sake. We can agree on the structure to include information on |
Beta Was this translation helpful? Give feedback.
-
|
I also think that having one page linked at both places is interesting. I wonder if the So three related concepts (event page, IDL/API property , HTML attribute) in one. |
Beta Was this translation helpful? Give feedback.
-
|
Yep, |
Beta Was this translation helpful? Give feedback.
-
|
Not certain about BCD. Often there is more than one onXxxx endpoint to think about - consider the global event handlers. Does that impact this idea? For FF93 I just documented new global onXXX handlers for slotchange and securitypolicyviolation. I think you are suggesting that using this new approach we have a combined (on)event page. Before the update this page might perhaps have an "Event Handler" section that stated that the event can be attached to Window, Document, Element (or whatever) using Further, assuming SVG is also impacted, this would also mention the SVG items that could fire the events and have the handlers? I'm a little concerned how you would show the corresponding compatibility information. From a docs point of view I find this more intuitive - one place for all docs around each event where you list everything that can trigger it and everything that can catch it. A pity we can't also combine the actual "event object" docs in there too. My feeling is we should prototype such a page, including at least one global event handler, all the way through to BCD. If that can be made to work then this would be much better. |
Beta Was this translation helpful? Give feedback.
-
|
The I don't quite follow the concern about SVG, it seems to me just like HTML, with both content attributes and event handler attributes. Or does the concern also apply to HTML? Given a single page for each even, I think the following should be listed:
In compat tables, I think it makes sense to treat support as partial if any of these aspects aren't what they should be, like if the event doesn't bubble but should, if it uses I'm not totally sure about the structure in BCD, however. It would actually be much easier to maintain the data if it's split apart into all the individual aspects, including splitting |
Beta Was this translation helpful? Give feedback.
-
|
Oh, and for a prototype, https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volumechange_event is already a pretty good example of this. It mentions both ways of listening for the event, and there's just one compat table. What's missing:
|
Beta Was this translation helpful? Give feedback.
-
|
mdn/browser-compat-data#12510 prototypes the BCD side of this. The manual work needed to just merge the existing data is considerable, and to actually review this for correctness would be quite some work. Nevertheless, I think the result will be better for anyone asking the simple question "can I use this event?" |
Beta Was this translation helpful? Give feedback.
-
|
I think having |
Beta Was this translation helpful? Give feedback.
-
|
There are different spec event lists here:
The second and third mention volumechange as global event but there is a remark: "While these attributes apply to all elements, they are not useful on all elements. For example, only media elements will ever receive a volumechange event fired by the user agent." |
Beta Was this translation helpful? Give feedback.
-
|
api.AbortSignal.abort_event api.AbortSignal.onabort AbortSignal.onabort Given the current practice is to have MDN pages and BCD entries for both, "_event" and for "onXXX", an agreement to one of these instead of two would spare around 400 pages (ignoring mixins for now). |
Beta Was this translation helpful? Give feedback.
-
|
AbstractWorker.onerror |
Beta Was this translation helpful? Give feedback.
-
|
I think that by and large we shouldn't do this. Many of those events do fire on specific types of objects, in particular a lot of them fire on specific HTML elements. Some of them bubble, which is why the event handler attributes ended up global. But not all of them do. |
Beta Was this translation helpful? Give feedback.
-
|
mdn/browser-compat-data#12510 proposes to use "_event" BCD entries (and I assume also analog MDN slugs) while removing the "onXXX" entries (and their MDN pages). Thoughts on what we are in favor of? The onXXX properties seem a bit old fashioned, however, they are at least nicely obtainable from IDL. |
Beta Was this translation helpful? Give feedback.
-
|
I think this particular case looks much better in terms of the docs. I'm still not clear for BCD - in particular for the rules for cases we discussed here: https://github.com/mdn/content/discussions/9098#discussioncomment-1361046
So for this example my assumption from BCD would be that onreflectionchange exists and is only on XRLightProbe. But if this was a global handler, it is not clear how I would represent the fact that the handler is global, and the cases it could be used. I'm not ruling out that I'm being thick. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks, I'm glad this approach is liked at least for "local" events. I'll work on an example PR for a "global" event next. It is possible that we want something like the _globals folder for these (cf. https://github.com/mdn/browser-compat-data/tree/main/api/_globals) and that MDN should talk about these as global events in some tree or at the top level. In the MDN HTML docs, they also got a separate page tree: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes Edit: A few real global events seem to be: error, languagechange, offline, online, rejectionhandled, unhandledrejection. |
Beta Was this translation helpful? Give feedback.
-
I believe by this you mean events like "message" that can be fired at a few different objects: Window, EventSource, WebSocket, MessagePort, BroadcastChannel, DedicatedWorkerGlobalScope, Worker, ServiceWorkerContainer. |
Beta Was this translation helpful? Give feedback.
-
|
@Elchi3 With respect to emitting events ^^^ https://github.com/mdn/content/discussions/9098#discussioncomment-1620405 I'm probably just confused. Consider abort_event, I see it as being fired by a number of objects: abortsignal, filereader, htmlmediaelement, idbdatabase, idbtransaction, xmlhttprequest (these are the pages that currently exist on MDN with the name Then I'm also worried about determining what can handle an event and how I mark that. This is not just a BCD question, I am generally not certain. My "thinking" is that you can
Sorry if this is just completely off track. I am sure this will become clear as you add examples. |
Beta Was this translation helpful? Give feedback.
-
|
I think a good case to help figure out some of the complexities here is all of the "change" events. There are bubbling "change" events fired at various form elements and I think almost all events can be given a sensible "owner" object based on what type of object it's fired on. A notion of global events could be useful for events that fire on both |
Beta Was this translation helpful? Give feedback.
-
|
Looking at the MDN page I think this is much much better 👍 |
Beta Was this translation helpful? Give feedback.
-
|
We agreed on a new template for a unified event page: https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types/API_event_subpage_template The backlog to unify all existing event pages is here: mdn/browser-compat-data#14578 The Serial API (https://developer.mozilla.org/en-US/docs/Web/API/SerialPort/connect_event) is an example how we dealt with bubbling. More details on this will follow as we encounter more bubbling events. The goal is also to get rid of mixins as much as we can. Again, will probably have more details on that once we hit these events in the backlog. Help appreciated as there are a lot of events. |
Beta Was this translation helpful? Give feedback.
-
|
Closing as answered/settled. |
Beta Was this translation helpful? Give feedback.
We agreed on a new template for a unified event page: https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types/API_event_subpage_template
The backlog to unify all existing event pages is here: mdn/browser-compat-data#14578
The Serial API (https://developer.mozilla.org/en-US/docs/Web/API/SerialPort/connect_event) is an example how we dealt with bubbling. More details on this will follow as we encounter more bubbling events.
The goal is also to get rid of mixins as much as we can. Again, will probably have more details on that once we hit these events in the backlog.
Help appreciated as there are a lot of events.