Readers/Web/Dev notes/Menu architecture (Vector)

The Page Tools project will involve substantial changes to the menus in Vector 2022. Vector already modifies it's menus quite heavily, and if we don't organize the code now, adding more logic will lead to more confusion, tech debt and potential bugs. We have to find a sane way to modify the menu-related code in Vector and make future modifications manageable.

Current challenges

• Menu modifications takes place in different parts of the code: hooks, in SkinVector.php and SkinVector2022.php
• The Menu.mustache template has large amount of conditionals
• The addition of icons to menu items takes place in different places in the code
• No clear separation of responsibilities between SkinVector.php and SkinVector2022.php

Areas of exploration

• Template refactoring
• Division of logic between PHP and Mustache templates
• Architecture of skin data modifications (i.e. can we structure these modifications in some sort of pattern).
• Normalizing skin data for templates

Timeline

3 October 2022

Patch: POC: Refactor user menu dropdown to use multiple menu groups

Participants: Bernard, Moh

Summary: "I talked to @Moh about this, we decided that we could use SkinComponents to create SkinComponentDropdown and use SkinComponentMenu in order to better organize this data. Moh will be writing a task to clean this stuff up and implement those classes." - comment

4 October 2022

Task: Split up Menu.template into separate templates, remove SkinVector::decoratePortletsData from modern Vector

Task goals: Split the Menu.mustache into multiple templates.

5 October 2022

Patch: [Technical] Split up Menu.template, restrict decoratePortletData to legacy Vector

Summary: Merged Nov. 2.

New template structure & code is moved from SkinVector.php to SkinVectorLegacy.php so that responsibilities are more clear.

New templates:

• Menu.mustache
• Portal.mustache
• Dropdown.mustache
• Tabs.mustache

18 October 2022

Meeting: Template Changes for Article Tools

Participants: Bernard, Jan, Mohd

Summary: Notes. Agree that we need a core Menu.mustache template that's shared across multiple menus. Question: How much data manipulation do we do in the templates vs in PHP?

20 October 2022

Meeting: Jan, Berard

Summary: Notes exploring potential menu structures. How do we handle the "pinnable" template inside a potential Dropdown template?

31 October 2022

Meeting: Super happy dev time - Path forward for menus

Summary:

1. Split templates

- from Menu.mustach into Dropdown.mustache & Portals.mustache

- Accept array as menu data for Article Tools menu

- Dropdown will be duplicated for pinnable feature

2. SkinComponents

- Modifications of data for menus. We're already heavily modifying menu data.

- create core menu/menuData component

- Proof of concept: https://gerrit.wikimedia.org/r/c/mediawiki/skins/Vector/+/850293

3. Composition

- How do we stuff data into child templates in Mustache without composability?

- We need to do more analysis on the solution to composition

November 7, 2022

Patch: [Technical] Separate Dropdown template into 3 templates

Summary: New structure for templates that allows for "faking" composability. Removes the need to use getTemplateParser in skinVector.php.

New templates:

• Dropdown.mustache
• Dropdown/start.mustache
• Dropdown/end.mustache

The template can now be used similar to how you'd use a <slot> tag in Vue.

{{>Dropdown/Open}}
	... any content can be placed here.
{{>Dropdown/Close}}

8 November 2022

Meeting: Bernard, Nick, Jan

Summary: Compared approaches to handling Dropdown data. Discussing Replace 'more' menu with page tools pinnable dropdown vs. Create new Page Tools menu (feature flagged). Agreed that iterating over an array of menu content is preferable to hard-coding menu content in Mustache. Why? We have to iterate over the sidebar menu content anyway, and handling the menu data in PHP makes it modifiable by extensions.

11 November 2022

Patch: Replace 'more' menu with page tools pinnable dropdown,

Summary: As of now, the data and templates for the Page Tools menu (a.k.a a pinnable dropdown) follow the diagram below.

A code flow diagram showing how data from SkinVector2022.php flows into the mustache templates.

28 November 2022

Meeting: Bernard, Nick, Jan, Jon, Moh

Summary: Discussed how templates should be organized, the two main options being generic templates (i.e. Dropdown.template) vs templates using composition (i.e. LanguageDropdown.template using Dropdown/Open.template and Dropdown/Close.template). Google Diagram illustrating options. Most engineers preferred to go with the latter option, and attempt to "vueify" mustache. On the backend side, we agreed it was best for Moh to focus on providing a VectorComponentDropdown class.

In followup conversations in Slack, Bernard raised concerns around how composition templates would work with pinnable dropdowns, and how that approach could result in more code duplication and template bloat.