-
Notifications
You must be signed in to change notification settings - Fork 144
Update DefaultAPISidebar macro for new event organisation #1314
Comments
Here's how I think DefaultAPISidebar works, what it's supposed to be for, and what we'll need to change. How it worksInputsThis macro gets passed a string. This is intended to identify a "group" in the GroupData macro, like "Ambient Light Events" or "Channel Messaging API". I'm not sure what determines whether group names get the " API" suffix, that seems random. We load GroupData and find the group, and use it to initialize some arrays:
We also initialize:
OutputsWe then write out:
What's it for?As I understand it this sidebar is supposed to be for pages that document what we call "APIs" as opposed to "interfaces". The difference is that an "interface" is a single concrete object that a web developer might encounter, while an API is a more abstract collection of features, that may include multiple interfaces and also individual methods belonging to other interfaces. Generally it seems that APIs align with specifications. For example. There's an API we call the Fetch API, that contains all the stuff under the abstract concept of Fetch. This includes specific objects (interfaces) like To document this abstract thing called "Fetch", we have an overview page whose name is usually (but not always) of the form "APIName_API". This page gives an overall description of the API. It may also have subpages, which are guides to aspects of the API. For example: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API, which has child pages like https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Cross-global_fetch_usage. So, the idea is that we use DefaultAPISidebar for pages like this. Then:
So what about events?So this brings us to For example, under the "File API" we currently have:
There events all target the However, under the "Clipboard API" we have:
In this case these events - Then we also need to update DefaultAPISidebar so it treats events in the same way as methods and properties - currently the macro assumes that events live under Web/Events. And before that of course we have to write tests for this macro. I also think there are other changes we ought to make to DefaultAPISidebar and GroupData, to make it all a bit more sensible. But that's out of scope for the event reference work. |
What should we use as a separator for I feel like a |
Yes, this is a good point, thanks! Perhaps we should use "Interfacename: eventname", like the page titles? We'd then I suppose have to transform that into "Web/API/Interfacename/eventname_event" for the link target. |
@chrisdavidmills , @Elchi3 , please let me know if you think the above sounds like a good approach. |
GroupData updatesI've made a first pass through the events in GroupData, summarised in this sheet: https://docs.google.com/spreadsheets/d/1-G5q6sqiT6iSz-O3tJMhdDjBWazXUvXeVoyP6eWH4X0/edit#gid=0. It has one row for each group that has a non-empty
Most have a clear answer: there are a few that will need a deeper look. |
@wbamberg this seems reasonsable to me. |
Sounds good to me, too. |
GroupData and DefaultAPISidebar updates are now merged and deployed (mdn/kumascript#1136), and pages like https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events and https://developer.mozilla.org/en-US/docs/Web/API/Touch_events are showing what we would expect: |
This is a work item for #685, and was originally discussed in #906.
The DefaultAPISidebar macro currently refers to GroupData to list events. We need to change this as part of the event refactoring wok, and instead treat events more like other subpages of the API (e.g. properties and methods).
Like APIRef, DefaultAPISidebar is complex. Although it's not as widely used as APIRef we should still add tests before making this update. So a prerequisite for changing it is adding tests.
In this user story we will:
AC are that both those changes are committed to KumaScript, deployed, and verified.
The text was updated successfully, but these errors were encountered: