Content bug: KeyboardEvent articles "Key values" and "code values" have no sidebar + are not linked in the KeyboardEvent sidebar

[caugner]

(Extracted from mdn/yari#5574)

What page(s) did you find the problem on?

1. Two KeyboardEvent articles:
   • https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values
   • https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values
2. The sidebar on other KeyboardEvent articles:
   • https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent

Specific page section or heading?

Sidebar on the left.

What is the problem?

1. The left sidebar is empty.
2. The left sidebar does not have links to "Key values" and "code values".

What did you expect to see?

1. The articles should have a sidebar.
2. The KeyboardEvent sidebar should link to the "Key values" and "code values" articles.

Did you test this? If so, how?

Tested by visiting the URLs above.

[wbamberg]

This is a bit tricky.

There are basically 2 sorts of sidebars that pages under Web/API get:

• sidebars for "APIs" such as Fetch API are built using the DefaultAPISidebar macro, and should get links to:

  • an overview page for the API, like Fetch API itself
  • a collection of guides for the API: these are generally pages living underneath the overview page, like Using the Fetch API
  • a collection of the interfaces that make up the API

• sidebars for "Interfaces" such as Request are built using the APIRef macro, and should get links to:

  • the overview page for the API that contains this interface
  • methods, properties, and events on that interface
  • related interfaces

The content of DefaultAPISidebar sidebars are mostly driven by the content of the GroupData.json file, and the content of APIRef sidebars are mostly driven by the pages underneath the interface page (which are generally property, method, and event pages).

There's much more on this here: https://discourse.mozilla.org/t/defaultapisidebar-apiref-and-groupdata/40210.

So. KeyboardEvent is an interface page, so it won't list guide pages. It just lists properties, methods, and events of the KeyboardEvent interface.

But KeyboardEvent: code values and Key Values are not properties, methods, or events. They are more like guide pages, and we don't list guide pages in interface sidebars.

So, the simplest suggestion is:

• move these two pages underneath the overview page for the API that definesKeyboardEvent
• add entries for these two pages to the entry in GroupData for that API

Except... we don't have an overview page for this API. We do have it listed in GroupData, as "DOM Events", but there's no overview page, so nowhere to put guides. So we also need:

• write an overview page for DOM Events

That way at least these pages would show up in the sidebar for the DOM Events API. They still wouldn't show up in the sidebar for KeyboardEvent though, because interface sidebars doesn't show guides. It turns out we talked about this before, so maybe we should extend APIRef to list guides.

Of course beyond all that there is the whole question about having better sidebars for Web/API pages, but that's a much bigger issue...

Tagging @teoli2003 who's probably interested in this.

[wbamberg]

Oh! I now see that the reason I didn't file an issue to write a "DOM Events" overview page before, was that we were going to fold this into "DOM": mdn/sprints#1537. I don't know if that is a good idea or not.

[wbamberg]

...and it looks like "UI Events" might be a better name anyway: https://w3c.github.io/uievents/.

[teoli2003]

I just opened #15753 to help here. Doesn't solve the whole problem but at least we can navigate logically out of these pages with it.

[teoli2003]

@wbamberg and I had a very interesting discussion about this today.
Here is what we plan to do:

• Move Event and EventTarget out of the DOM Events group, into the DOM group (updating the sidebar for these interfaces and their children.
• Adapt {{APIRef}} to display guides (This is what {{DefaultAPISidebar}} does, so we don't invent a mechanism there.
• Rename DOM Events to UI Events in GroupData.json (and adapt the sidebar macro in the relevant pages).
• Create a new "UI Events API" overview page.
• Move Code_values and Key_values (fixing capitalization) under that overview page and fix the links leading to it.
• Add these two pages under a new Guides section (of "UI Events API") in GroupData.json.

Sounds like we have a plan.

[wbamberg]

I'm glad there was such a simple fix to this problem! /s

[wbamberg]

I filed mdn/yari#6229 to capture "Adapt {{APIRef}} to display guides", which I think isn't really relevant to the original issue here.

[teoli2003]

Changing {{APIRef}} to {{DefaultAPISidebar}} and morphing these two pages into guides solve two-thirds of the problem: navigating out and between these pages.

This is better than anticipated when we discussed the plan. 🍾

We still have a problem navigating to these pages from KeyboardEvent (or one of its children). mdn/yari#6229 is still needed for it. But I can live without it for a long time.

[wbamberg]

Yeah, also it's possible that some bigger improvements to Web/API sidebars might make mdn/yari#6229 moot :).