Event page type & structure

[Elchi3]

Now that we seem to be in agreement to unify the event pages (https://github.com/mdn/content/discussions/9098), this discussion is about how to design the new event page that talks about both the onXXX event handler and the event itself. This means we are creating a new page type.

Examples for unified pages that I have created so far are:
https://developer.mozilla.org/en-US/docs/Web/API/XRLightProbe/reflectionchange_event
https://developer.mozilla.org/en-US/docs/Web/API/XRReferenceSpace/reset_event

The new outline is:
Syntax
Event type
Examples
Specifications
Browser compatibility

"Event type" is new and I thought of it like "Return value" on method pages, so I thought it deserves its own section. Maybe it should be an h3 and under Syntax (also new!), though.

Typically Event pages have tables. See e.g. https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volumechange_event. I'm not sure if a table is the best way to communicate the information. I think I'm keen on trying to get rid of it. However, I'm happy to hear other thoughts.

So, how should we structure unified event pages?

[wbamberg]

Thanks for starting this conversation!

• I think "Syntax" is going to have a lot of boilerplate here - won't it always be effectively the same except for the event name (excepting some events which don't have on-* properties, and even then the first part will be the same). So I'm not sure how much information this really conveys. We already know the event name.

• For "Event type" it looks weird to me to have an H2 section which contains just one word. "Return value" quite often has a fair bit of information beyond just the type of the return value. For instance, without looking at all hard I found https://developer.mozilla.org/en-US/docs/Web/API/XRReferenceSpace/getOffsetReferenceSpace#return_value. Will we often have similar levels of detail for "Event type"?

• For "Examples", I'm not sure whether we need both variants. Again this will get very repetitive. Once people know how to assign to an on* property for one event, they know how to do it for all events. I think. it's more important. to have examples that show the real usage of the event than ones that just demo the syntax (like this: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/loadstart_event#examples although this is broken 😭 ).

• https://developer.mozilla.org/en-US/docs/Web/API/XRReferenceSpace/reset_event has an H2 "Usage notes" - I think it would be better to use "Description".

There are obviously a few bits of common information that event pages should have a consistent way to represent, and that's what these tables were trying to do. The basic tables (e.g. https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/loadstart_event) have:

• link to the interface page for the event object (the thing that gets passed into the listener)
• does it have an on* property (AIUI this is "usually but not always"). Given an event eventname, is the property always named oneventname or are there exceptions here, where the on* property has a different name? That is, can we represent this just a boolean "does it have an on* property", or is there more information we should represent? If there are exceptions, are they rare enough that we should treat it as a boolean and loudly flag the exceptions?
• "cancelable" which is captured here in prose, which seems fine to me. I think you said it's almost always no anyway.
• "bubbles" is dropped, which I guess is fine.

Some tables, like https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volumechange_event, have extra stuff, and I'm not sure it's worth capturing that.

I'm not sure if a table is the best way to communicate the information. I think I'm keen on trying to get rid of it.

I'd like to understand better the rationale for this. We use tables like this in a few different page types on MDN (e.g. HTTP headers, HTML elements, CSS properties. Are we intending to deprecate them generally? I think tables are quite a good way to present this kind of very structured data, where there's not a lot of nuance for the values (I think tables tend to fall apart when the values need a lot of description, which is why they're not a good way to represent parameters).

One obvious problem with them is that Markdown hates them, and they are a real pain to write in HTML. We've talked before about generating them though, which avoids this problem. But apart from that, I'd like to understand why we don't like them (I'm not a huge defender of tables, would just like to understand the reasoning). Is there a user-facing reason to deprecate them?

[Elchi3]

Thanks for your very detailed feedback, Will!

• I think "Syntax" is going to have a lot of boilerplate here - won't it always be effectively the same except for the event name (excepting some events which don't have on-* properties, and even then the first part will be the same). So I'm not sure how much information this really conveys. We already know the event name.

Yes, I think syntax boxes will mostly be the same. Maybe syntax boxes aren't a good idea. Ideally, I think, early on this page we want a way to show what you can do here. So, for events you can use the event name or the event handler property and respond to an event. Sometimes, there is also an HTML content attribute as well (<a onclick="foo"></a>). Sometimes, you don't have the onXXX event handler as you say. If not using a syntax box, is there something easily recognizable/scannable that quickly gets across what this whole page is talking about?

• For "Event type" it looks weird to me to have an H2 section which contains just one word. "Return value" quite often has a fair bit of information beyond just the type of the return value. For instance, without looking at all hard I found https://developer.mozilla.org/en-US/docs/Web/API/XRReferenceSpace/getOffsetReferenceSpace#return_value. Will we often have similar levels of detail for "Event type"?

I'm not sure if there is going to be more details to an "Event type" section. I think it is quite important information, though. An event can just be of type "Event" or have a dedicated type like "XRReferenceSpaceEvent". Now the important piece of information is what kinds of additional properties you will have available if it is not just of type "Event". I'm not sure if it is a good idea to put that info from say the XRReferenceSpaceEvent page on the event page in the "Event type" section. Maybe it is?
When it was in the table, it didn't feel prominent enough to me. Also it is often called "Interface" in the table and that feels too generic to me.

• For "Examples", I'm not sure whether we need both variants. Again this will get very repetitive. Once people know how to assign to an on* property for one event, they know how to do it for all events. I think. it's more important. to have examples that show the real usage of the event than ones that just demo the syntax (like this: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/loadstart_event#examples although this is broken 😭 ).

Yes, I think the assumption is that onXXX event handler examples are "old school". Not really deprecated or discouraged, but using the event name and add/removeEventListener and friends seems much more common.

• https://developer.mozilla.org/en-US/docs/Web/API/XRReferenceSpace/reset_event has an H2 "Usage notes" - I think it would be better to use "Description".

Agreed.

There are obviously a few bits of common information that event pages should have a consistent way to represent, and that's what these tables were trying to do.
The basic tables (e.g. https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/loadstart_event) have:

• link to the interface page for the event object (the thing that gets passed into the listener)
• does it have an on* property (AIUI this is "usually but not always"). Given an event eventname, is the property always named oneventname or are there exceptions here, where the on* property has a different name? That is, can we represent this just a boolean "does it have an on* property", or is there more information we should represent? If there are exceptions, are they rare enough that we should treat it as a boolean and loudly flag the exceptions?
• "cancelable" which is captured here in prose, which seems fine to me. I think you said it's almost always no anyway.
• "bubbles" is dropped, which I guess is fine.

Some tables, like https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volumechange_event, have extra stuff, and I'm not sure it's worth capturing that.

I'm not sure if a table is the best way to communicate the information. I think I'm keen on trying to get rid of it.

I'd like to understand better the rationale for this. We use tables like this in a few different page types on MDN (e.g. HTTP headers, HTML elements, CSS properties. Are we intending to deprecate them generally? I think tables are quite a good way to present this kind of very structured data, where there's not a lot of nuance for the values (I think tables tend to fall apart when the values need a lot of description, which is why they're not a good way to represent parameters).

One obvious problem with them is that Markdown hates them, and they are a real pain to write in HTML. We've talked before about generating them though, which avoids this problem. But apart from that, I'd like to understand why we don't like them (I'm not a huge defender of tables, would just like to understand the reasoning). Is there a user-facing reason to deprecate them?

I mainly got rid of the tables, because I wasn't really sure what is left if you remove the interface (becomes "Event type"), the onXXX name (not very useful, as it is always the expected name), "cancelable" (just write it in prose if it is cancelable), and "bubbles" (if it bubbles mention it, but most don't, so why have this in every table?).

I mean if we think that events should always talk about what's currently in the table, then that's our structured data for events and we could choose a table to display that data. But to me it seems like these things aren't all that useful to the reader most of the time and there are maybe better ways to present the information that matters? (event type matters a lot but cancelable, bubbles and onXXX handler not so much).

[wbamberg]

• For "Event type" it looks weird to me to have an H2 section which contains just one word. "Return value" quite often has a fair bit of information beyond just the type of the return value. For instance, without looking at all hard I found https://developer.mozilla.org/en-US/docs/Web/API/XRReferenceSpace/getOffsetReferenceSpace#return_value. Will we often have similar levels of detail for "Event type"?

I'm not sure if there is going to be more details to an "Event type" section. I think it is quite important information, though. An event can just be of type "Event" or have a dedicated type like "XRReferenceSpaceEvent". Now the important piece of information is what kinds of additional properties you will have available if it is not just of type "Event". I'm not sure if it is a good idea to put that info from say the XRReferenceSpaceEvent page on the event page in the "Event type" section. Maybe it is? When it was in the table, it didn't feel prominent enough to me.

I absolutely agree that it's important information. I'm very tempted to want it to include more details, especially about any extra properties in addition to the basic Event properties. But then of course we get into the problem of duplication.

One thing I would say though is that IMO for reference pages consistency is more important than prominence. I don't need it to be in big letters so much as I need it to be always in the same place.

Also it is often called "Interface" in the table and that feels too generic to me.

I'm not sure "Type" is less generic/more understandable though. Note we use "Type" in a different way here: https://developer.mozilla.org/en-US/docs/Web/Events#event_index, and the specs seem to use "Type" to mean animationcancel, etc (https://drafts.csswg.org/css-animations/#event-animationevent).

Maybe it's worth being more explicit and calling it something like "Event handler argument"?

---

As a reader, the main things I'd want to know when I visit a page like this are:

• trigger: exactly when is this event triggered?
• event handler argument: what additional information is available to the event handler? As a reader I'd love a description here of any interesting properties, but as said above this gets into the problem of duplication.
• use cases: what might people want to use this event for? What should they not use it for? For instance it's helpful to say that visibilitychange is a good way to track the end of a user's session, while unload is not.
• related events: which events are similar to this one or are related to it in some way (e.g. other animation events). What are the salient differences between them (this is like "See also" of course but maybe more specific)

I don't need to know that I can use addEventListener to listen for it, I know that already.

If we can agree on something like this, is it worth trying to make a structure that makes it explicit? Could each of these be an H3 under Description?

[Elchi3]

I absolutely agree that it's important information. I'm very tempted to want it to include more details, especially about any extra properties in addition to the basic Event properties. But then of course we get into the problem of duplication.

I'm happy to experiment with this. Duplication is an authoring burden that we can take if the benefit for the reader is rather large.

One thing I would say though is that IMO for reference pages consistency is more important than prominence. I don't need it to be in big letters so much as I need it to be always in the same place.

Excellent point, agree with this.

Maybe it's worth being more explicit and calling it something like "Event handler argument"?

hm yeah type has several meanings, too. I think "Event handler argument" is quite specific on the other hand because it is more than just the argument? Not sure.

If we can agree on something like this, is it worth trying to make a structure that makes it explicit? Could each of these be an H3 under Description?

https://developer.mozilla.org/en-US/docs/Web/API/XRSystem/devicechange_event is a page that uses h3 headings now and has no syntax box. Feedback on this page?

[jpmedley]

Event type sections currently have something like:

An {{domxref("XRLayerEvent")}}. Inherits from {{domxref("Event")}}.

We should just use the inheritance diagram macfro. The macro doesn't say event or or interface. It just shows the relationship and provides links and does so with automation. To provide this manually I have to look it up. Further more, if an inheritance sequence is expanding by adding upstream items, no one has to remember to update event pages. (This happens sometimes. Remember the audio classes that got base classes a few years ago?)

[Elchi3]

I've opened mdn/content#11025 to test this proposal.

[Elchi3]

A new template for event pages has been agreed on: https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types/API_event_subpage_template

The backlog to update existing pages is here: mdn/browser-compat-data#14578