Manual:Skins/Menu API specification (draft)
This article outlines the specification for a new core menu API to generate and modify data for MediaWiki menus.
Background & Motivation
As part of the Skin Platform evolution efforts, the primary goal of this work is for menus to be easily registered and modified by skins and extensions. Historically Skin code and inheriting skin classes have used various hooks (many targeted for deprecation) and custom code to override and extend menus. As a result, skin code has become overly complex and convoluted with growing technical debt. We need a sustainable way for menus to be built and customized by technical contributors and eventually by community members administrating MediaWiki instances.
Specification
The API returns well-formed data structures representing the discrete, granular data of a menu group and its corresponding menu items for passing into templates for rendering.
Data structure
Each menu group is prefixed with "data-" to encapsulate all of the related menu items under the menu group. Every menu item provides structured menu data in the following format:
- name - the name of the menu item
- components - a structured array containing the following keys:
| Name | Type | Description |
|---|---|---|
| id | String | The unique id of the menu link item |
| text | String | The text of the menu link item |
| href | String | The link URL source |
| class | String | A space delimited array of class names |
| <custom> | String | (additional custom key/value pairs) |
Mustache template keys
A set of default menus are available in core for all inheriting skins. Skins are able to override which default menus' data are output via config. The default menus are defined as:
- Actions
- Associated Pages
- Notifications
- User Interface Preferences
- User Menu
- User Page
- Views
- Variants
File:Orange check.svg <translate> Partially done</translate>
data-actions
The Actions menu group contains menu link data for the allowed actions of the current user: add, move, delete, protect, watch, etc.
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
data-associated-pages
Formerly known as "namespaces", the Associated Pages menu group contains menu link data for the list of navigation links to pages that are related to or associated with a special page.
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
data-notifications
The Notifications menu group contains menu link data for notifications
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
Deledetions shourtcuts. / deledetionsource
The User Menu menu group contains menu link data for the current user's personal tools: talk pages, preferences, watchlist, contributions, login/logout, create account, etc.
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
data-user-page
The User Page menu group contains menu link data for the current user's page.
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
data-views
The Views menu group contains menu link data for the allowed views of the current user: view, edit, view source, add section, history, etc.
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
data-variants
The Variants menu group contains menu link data for all the available language variants of the page.
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
Because of the current state of footer templates (to be retrofitted to accept the new menu data structure), the data-footer group of footer-related menu groups and items are treated separately from the default menus. Inside data-footer, the following data keys are available:
- data-info
- data-places
- data-icons
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
Hooks
In order for skins and extensions to register new menus or modify existing menus, a hook is provided for overriding. Until/if/when the SkinTemplate class is fully decommissioned, the SkinTemplateNavigation__Universal hook will be used for this purpose.
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
The new hook must allow for removal of menu items to an existing menu
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
The new hook must allow for addition of menu items to an existing menu. When adding a menu item, it should be possible to add to the beginning, append after an existing item, or add to the next available space in the menu.
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
The new hook must allow for creation of new menus.
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
Configuration
Skins
Modern skins can provide a "menus" skin option (ValidSkinNames[skinkey][args][0] in their skin.json file with a list of their preferred menus' data to be output. If the "menus" property contains a given default menu key, the corresponding data will be output under the relevant data heading (currently "data-menus-default" or "data-footer").
File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
When a modern skin defines a "menus" skin option the legacy data (data-portlets) will not be available to the Mustache template for rendering. File:OOjs UI icon reload-progressive.svg <translate> In progress</translate>
Extensions
Validation
We should ensure that there are no duplicate ids in the outputted menu data.
Order of Precedence
The new menu system defines a clear order of precedence between skins, extensions, and gadgets.
Duplication
There is a use case for duplicating menu items whether moving menu items to different menu groups or cloning menu items/groups (in the case of sticky header for example - there are duplicated edit buttons).
We need a way to change or append to menu IDs.
Unit Tests
File:Yellowpin.svg <translate> To do</translate>
Backwards Compatibility
To maintain backwards compatibility, only skins that contain the "menus" property with any number of arguments representing an available menu in their skin.json will generate the menu groups menu link data and the default data generation keys will be removed. Otherwise the default data generation keys will continue to be output to serve skins that do not specify a "menus" property.
File:Yellowpin.svg <translate> To do</translate>
Suggestions | Discussions
https://docs.google.com/document/d/1Pf175Ur31KIZA9j-E1ZFhbx3VYcMvSpzJYyt9YDRNbI/edit
