Feature summary (what you would like to be able to do and where):
There should be a function to create a new portlet section that can be used in scripts and gadgets, similar to how mw.util.addPortletLink can be used to add an individual link to a portlet.
Use case(s) (list the steps that you performed to discover that problem, and describe the actual underlying problem which you want to solve. Do not describe only a solution):
There are various scripts and gadgets across Wikimedia projects which create a new portlet section. They all have to generate the corresponding HTML themselves and have to be updated when the HTML for a portlet section changes, which has happened twice in the last year already.
e.g.
- https://meta.wikimedia.org/wiki/MediaWiki:Gadget-MoreMenu.js#L-586
- https://commons.wikimedia.org/wiki/MediaWiki:InterProject.js#L-48
- https://commons.wikimedia.org/wiki/MediaWiki:Gadget-AnonymousI18N.js#L-342
- https://github.com/wikimedia-gadgets/twinkle/blob/49207b07d0a10496f2552b36281937b5eee72caf/twinkle.js#L222-L402
Benefits (why should this be implemented?):
It would be easier for script authors who wouldn't have to generate HTML themselves.
It would provide more consistency, since everyone who uses the function would get the same generated HTML.
It would mean scripts don't have to be updated whenever the HTML changes.
Background
Vector is the only WMF skin with native menu functionality. Menus are a nice way to consolidate a collection of links, as opposed to throwing them all into #p-cactions or #p-tb which can quickly become too large. mw.util.addPortletLink exists, but it only lets you add to existing portlets. If you want to create a new one, you must construct the HTML yourself. During the development of Vector-2022, this has caused repeated regressions and breakage in popular gadgets such as Twinkle and MoreMenu. It has even caused breakage in Core, namely Live Preview which also has to construct Vector HTML by hand (T262374, T303676).
There is a clear need for a JS method to create custom porlets. While there may not be a precedent for Core to support them, from which other skins can implement styling, Vector specifically seems to beg for this functionality.
T302073: [GOAL] Page Tools available on all wikis proposes even more radical changes to menus that will break gadgets, possibly in a way that is not backwards-compatible -- meaning that for gadgets used across different deployment groups, there will be a period where they are broken for some but not others. This is what happened on March 10, when gadgets maintainers waited for new HTML changes to arrive to group 2 before deploying the corresponding fixes. Although the fixes were deployed within minutes, it was still long enough to attract a flood of complaints. It would be much more ideal if we didn't have to construct the HTML ourselves and could rely on Vector to do it for us.
Proposal
Add a mw.util.addPortlet( locationId, id, label ) method, which allows to target certain parts of the UI. In Vector 2022/Vector locationId might be right-navigation (top-level menus) or mw-panel (sidebar portlets), however we should think about how this might work across skins (perhaps if the element is unavailable the JS throws an exception and the client must handle it)
Related conversation with @Jdlrobson at https://github.com/wikimedia-gadgets/MoreMenu/issues/25
@matmarex captured thoughts here: T303859#7779807
Acceptance criteria / QA steps
- It should be possible to create an empty menu
- It should be possible in Vector 2022 to style it as a dropdown
- When styled as a dropdown, clicking outside the new menu should close it (see related issue in T336965)
Check the following code adds a menu to the main menu.
var x = mw.util.addPortlet('foo');
$(x).insertAfter( '#p-navigation' );
mw.util.addPortletLink('foo', '#', 'New portlet link');
mw.util.addPortletLink('foo', '#', 'New portlet link 2');Check the following code creates a new dropdown menu
var x = mw.util.addPortlet('twinkle-2', { type: 'dropdown' } );
$(x).insertAfter( '#vector-page-tools-dropdown' );
mw.util.addPortletLink('twinkle-2', '#', 'Link inside a dropdown');Enable the Twinkle gadget on enwiki.
Run the following code in beta cluster and confirm that the links match up with those on enwiki:
var useCactions = [ 'monobook', 'cologneblue', 'modern' ].indexOf( mw.config.get( 'skin' ) ) > -1;
var portletId = useCactions ? 'p-cactions' : 'p-twinkle';
$('#p-cactions.emptyPortlet' ).remove(); // hack not needed
if ( !$( portletId ).length ) {
const p = mw.util.addPortlet(portletId, 'TW' );
$( p ).insertAfter( '#p-cactions' );
}
mw.util.addPortletLink( portletId, '#', 'csd', 'tw-csd' );
mw.util.addPortletLink( portletId, '#', 'prod', 'tw-prod' );
mw.util.addPortletLink( portletId, '#', 'xfd', 'tw-xfd' );
mw.util.addPortletLink( portletId, '#', 'rpp', 'tw-rpp' );
mw.util.addPortletLink( portletId, '#', 'tag', 'tw-tag' );
mw.util.addPortletLink( portletId, '#', 'last', 'tw-last' );
mw.util.addPortletLink( portletId, '#', 'unlink', 'tw-unlink' );