Browser-compat-data: Add events compat data

Created on 1 Feb 2018 · 10Comments · Source: mdn/browser-compat-data

We need to have a place to place compatibility data for events. I propose we add a top-level "events" folder, inside which we place the JSON files for each event.

Because the same event can be used by multiple interfaces, sometimes with different event interfaces (Event vs KeyboardEvent for example), we need to decide how to handle these. In content, we have shifted to documenting all of these on one page, with sections for each of the various versions of the event.

For BCD purposes, I propose that each specification's version of the event be placed in a file named eventname-interfacename, and that they be referenced using the name event.eventname.interfacename.

So for the KeyboardEvent named keydown, the file would be keydown-KeyboardEvent.json and it would be referred to using the name event.keydown.keyboardevent (or event.keydown.KeyboardEvent if we use camelcased names).

One outstanding question: If two specifications use the same form of the event, should they share a BCD file, or use separate ones? Sharing is tempting for convenience, but what if they deviate over time?

data infra

Source

a2sheppy

Most helpful comment

All legacy compat tables for events have been migrated and we have a convention for adding more in the future. Thanks everyone who was involved with this work.

Elchi3 on 2 May 2019

🎉3

All 10 comments

Hi Sheppy,

tl;dr;
id: event._eventname_._interfacename_ (_interfacename_ camelcased)
folder and filename: api/events/_eventname_.json

Complete answer

Yes, I think that having an id: event._eventname_._interfacename_ is the good way to go, as it makes easy to generate the BCD table on the event page.

For the naming of the files, I think we should have one file per _eventname_ which each entry for the different interface in there.

So keydown.json will contain an entry for event.keydown.KeyboardEvent and eventually another for event.keydown.OtherInterface

About your outstanding question, I think it isn't a problem: we don't document specs, we document implementation, so if 2 specs are incompatible, we document what is implemented.

teoli2003 on 2 Feb 2018

So keydown.json will contain an entry for event.keydown.KeyboardEvent and eventually another for event.keydown.OtherInterface

I concur. That's my preference. I think it will be easier to manage, and more in keeping with how we're moving toward doing the same in the documentation.

I take it, then, that the actual JSON would have something like:

{
  "event": {
    "Event": {
      "__compat": {
        ...
      }
    },
    "MediaStreamEvent": {
      "__compat": {
        ...
      }
    }
  }
}

The main question I have is about "event" as the top level name there; it seems incongruous given that what you're looking at are actually event targets. Should that be "target" or "interface" instead?

a2sheppy on 2 Feb 2018

What's the rationale for separating event targets from APIs? I was just thinking about how EventTarget and its subclasses manifest as interfaces from a developer's perspective.

mdittmer on 2 Feb 2018

@mdittmer - This isn't actually about event targets but about the events themselves. This is strictly about organizing the events, given that events by the same name can have different contents and meanings depending on which API they're used by. For example, the "close" event is used by WebRTC, WebSockets, IndexedDB, HTML DOM, and potentially others, and thus needs to be covered by the JSON in a way that allows us to identify which target the event is intended for, given that the event may have different contents.

We don't need to, and should not, I think, actually allow sub-features in the events JSON. The event interface names and the mdn_url referencing the event documentation should be enough, I think.

Sheppy

a2sheppy on 2 Feb 2018

Here's a list of event pages that currently store compat information.

Elchi3 on 7 Feb 2018

https://developer.mozilla.org/en-US/docs/Web/Events/close is in fact an extreme example and I don't like how the documentation is done there.

I don't know much about how MDN readers use event pages. I guess somewhere you have a "close" fired and then you want to read about it. However, the "close" page has not much information, no code samples, no details about each of the various close events.

Pages where there is only one event described, like https://developer.mozilla.org/en-US/docs/Web/Events/webglcontextcreationerror, are better imo, but the info is also similar to say the info on https://developer.mozilla.org/en-US/docs/Web/API/WebGLContextEvent.

So, I think "collection pages" like "close" are not really useful, except for pointing to pages where each of the close events is described in more details. So, if I were to document "close" events I would create something like:

Web/Events/close (disambig page, almost what we have right now)
Web/Events/close_HTMLDialogElement
Web/Events/close_IDBDatabase
Web/Events/close_RTCDataChannel
Web/Events/close_WebSocket

For browser compat data, we then either have the data in an own tree and by target interface like this (events/targetInterface.json is the file):

events.HTMLDialogElement.close
events.IDBDatabase.close
events.RTCDataChannel.close
events.WebSocket.close
events.HTMLCanvasElement.webglcontextcreationerror
events.HTMLCanvasElement.webglcontextlost
events.HTMLCanvasElement.webglcontextrestored

Or, we add events to the target interfaces directly, say like this (api/targetInterface.json is the file):

api.HTMLDialogElement.events.close
api.IDBDatabase.events.close
api.RTCDataChannel.events.close
api.WebSocket.events.close
api.HTMLCanvasElement.events.webglcontextcreationerror
api.HTMLCanvasElement.events.webglcontextlost
api.HTMLCanvasElement.events.webglcontextrestored

Elchi3 on 7 Feb 2018

OK, that makes sense. I still personally like them better on one page but I can see the issues you raise are legitimate ones, too. :)

If we make this change, we will also need to change the {{event}} macro to accept an additional parameter specifying the target interface name. Except it already accepts several optional parameters, and tacking the interface name to the end is really awkward.

So I propose we create a new macro to replace it, called perhaps {{EventXRef}}, with syntax like so:

{{EventXRef(eventname, targetinterface, text, anchor)}}

Examples:

{{EventXRef("negotiationneeded")}}
{{EventXRef("close", "HTMLDialogElement")}}
{{EventXRef("close", "WebSocket", "Usage note", "additional information")}}

Only the first parameter, eventname, is required. Additional behavior notes:

If the text parameter is included, the text should not be wrapped in a <code> block; otherwise it is.
Process the anchor to convert it into a valid ID before using it; that means converting spaces to underscores, stripping out or escaping special characters, etc. Exactly like we do for the {{anch}} macro, I think.

a2sheppy on 7 Feb 2018

We've started refactoring the event docs, please see: https://github.com/mdn/sprints/issues/685 (and discuss docs refactoring plans there)

As for adding events to this repo, we're now about to install them under "_targetInterface_._eventname__event". See the first two PRs on this:

https://github.com/mdn/browser-compat-data/pull/3469
https://github.com/mdn/browser-compat-data/pull/3420

I'm leaving this issue open until we're done refactoring and events compat data has been migrated.

Elchi3 on 18 Feb 2019

All legacy compat tables for events have been migrated and we have a convention for adding more in the future. Thanks everyone who was involved with this work.

Elchi3 on 2 May 2019

🎉3