Page MenuHomePhabricator

Per community request update documentation for addPortlet API
Closed, ResolvedPublic

Description

Background

The community provided feedback for one of the APIs we provide. (From https://meta.wikimedia.org/w/index.php?title=Talk:MoreMenu&oldid=26506053#c-Xover-20240329161100-Jdlrobson-20240324141900 and T359110 there is some confusion around the addPortlet API.)

User story

As a community gadget developer I want a better understanding of how the addPortlet API works.

Requirements

  • Fix the documentation for the before argument ("selector of the element preceding the new portlet" should presumably be "selector of the element the new portlet should precede"). I've tried adding some docs about the dropdown use case at #Dropdowns (Vector-only)
  • Document the skin specific behaviours relating to dropdown
  • Consider (with other engineers) providing further abstractions that specifically create a dropdown (where supported)

Communication criteria - does this need an announcement or discussion?

  • The addPortlet API should be announced in Tech News given we have evidence it is now useful. [T365661]

Event Timeline

Jdlrobson triaged this task as Medium priority.Apr 24 2024, 3:10 PM
Jdlrobson renamed this task from Update documentation for addPortlet API to Per community request update documentation for addPortlet API.Apr 25 2024, 7:55 PM
Jdlrobson updated the task description. (Show Details)

Change #1025882 had a related patch set uploaded (by Jdlrobson; author: Novem Linguae):

[mediawiki/core@master] addPortlet: improve documentation

https://gerrit.wikimedia.org/r/1025882

Change #1025882 merged by jenkins-bot:

[mediawiki/core@master] addPortlet: improve documentation

https://gerrit.wikimedia.org/r/1025882

Change #1035062 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/core@master] [Documentation] Improve documentation of addPortlet method

https://gerrit.wikimedia.org/r/1035062

Jdlrobson updated the task description. (Show Details)
Jdlrobson updated the task description. (Show Details)

Change #1035062 merged by jenkins-bot:

[mediawiki/core@master] [Documentation] Improve documentation of addPortlet method

https://gerrit.wikimedia.org/r/1035062

Jdlrobson claimed this task.

I think a dropdown API would be dangerous to add, as it assumes that Vector/Vector 2022 will always render menus in dropdowns and it's possible at some future date, we may change the API to have different behaviour. The addPortlet and addPortletLink methods have always been about creating the generic structure rather than visual appearance. Having a method called addDropdown also creates the concern that for skins where the concept of a dropdown UI doesn't exist, the function would lead to some confusion as the resulting element would not be a dropdown.

I think we are lacking necessary foundations to even be able to consider such an API at this time, in particular we need:

  1. A dropdown component in Codex that renders a dropdown identical to Vector
  2. Use of that new dropdown component inside Vector
  3. A new API that replaces addPortletLink and addPortlet for creating a Codex dropdown component (something best suited for Design-System-Team).

At the current time, I don't think gadget developers plugging into a skin can be responsible for UI in a way that we can stable - for now the responsibility needs to lie with the skin to do what makes sense with hints from the gadget developer. The current API at least permits a way to do this, but in a way that doesn't promise "this will always be rendered as dropdown forever.

I've opened T365661 to advertise this API, collect some more feedback, for more discussion.
If someone feels strongly this is needed, I recommend raising a new ticket for getting the dropdown component added, and then if and when that's done we can circle back to doing something inside skins.