User profile menu subsections

Last modified by Lucas Charpentier on 2026/11/19 16:25

Description

This proposal groups the entries of the user profile menu in collapsible subsections, so that the menu stays readable as extensions add entries and new preferences have an obvious place to go. It is implemented by XWIKI-22065.

Context

The user profile menu is a flat list of entries contributed by UI extensions on the org.xwiki.plaftorm.user.profile.menu extension point. XWiki Standard contributes 8 of them: Profile, Preferences, Groups, Network, Notifications, Wikis, Dashboard and Liked pages. At least 9 extensions outside the platform contribute more, in xwiki-contrib (activitypub, changerequest, gitlab, invoices, notification-word, mfa, oidc), in xwikisas (project-management) and in personal projects.

This is already more than Miller's law recommends, and it makes it hard to decide where a new preference goes, see Shortcut settings position and Changing order of notification autowatch.

Proposal

User interface

The menu becomes an accordion, styled like the administration menu:

  • Each group is a heading with an icon, a name and a caret. Clicking a heading only expands or collapses the group, it doesn't navigate.
  • Only one group is expanded at a time, like in the administration menu. When the page loads, the group holding the displayed entry is expanded.
  • A group without any entry for the current user is hidden.
  • The menu is always an accordion, even when a single group is displayed.

The default groups are:

GroupIconPriorityEntries
Profileuser100Profile, Groups, Wikis
Activitychart-bar200Network, Dashboard, Liked pages
Settingswrench300Preferences, Notifications
Othermenu10000Entries without a group, or with a group that doesn't exist

Extension points

A new extension point declares the groups: org.xwiki.platform.user.profile.menuGroup. Its id is spelled correctly, while the entry extension point keeps its plaftorm id so that the existing extensions keep working. A group UIX takes the following parameters:

  • id: mandatory, the group identifier. It is used to build the identifiers of the accordion, so a group without it is not displayed and a warning is logged.
  • icon: optional, the name of an icon of the current icon theme.
  • priority: the order of the group, sorted the same way as the entries.

The group name is always the translation platform.core.profile.menu.group.<id>, so an extension adding a group provides that key in its own translations. When several groups have the same id, the one with the lowest priority wins, as for the entries.

An entry chooses its group with a new group parameter, for example group=settings. All the other entry parameters are unchanged, including isActive.

The 4 default groups are UI extensions declared on a hidden page of the User Profile Application, XWiki.UserProfileMenuGroups. When the Other group has been removed, the entries without a valid group are not displayed and a warning is logged.

Implementation

  • A new skin macro, #verticalNavigationAccordion($menu $options) in macros.vm, renders the accordion. It reuses the Bootstrap collapse markup of the administration menu, without its search box, and its styles live in a new plain CSS file of the Flamingo skin, css/vertical-accordion.css.
  • XWiki.XWikiUserSheet loads the groups, puts each entry in its group and calls the new macro. Its JavaScript expands the right group when navigating through the browser history.
  • The 8 entries of XWiki Standard declare their group.
  • The menu entries keep their vertical-menu-<id> ids and the panes keep their <id>Pane ids. The entries now use the standard list-group-item and active classes and a data-id attribute, instead of category-tab and current. The xwiki:profile:switchedCategory event now carries the category id. The Network pane listener of this event, which expected the category id but never matched since 2014, is removed so that the Network pane keeps its current behaviour.
  • The unused styles of the old menu were removed: the Silk icons and the Colibri rules of the user sheet, and the Flamingo rule that hid those icons.

Dropped options

These options were considered while planning the implementation and dropped:

  • Splitting the Preferences pane into one entry per section (Display, Accessibility, Localization, Editor, Extensions, Security). It would change the edit and save flow of the preferences and many tests. The groups make it possible later, and the questions raised on the forum about the shortcut and autowatch settings can then pick a group.
  • A group list hardcoded in the user sheet. The menu is used by many extensions, so the groups are UI extensions, which extensions can add to.
  • A name parameter on groups. Group names are always translated, so the name comes from a translation key built from the group id.
  • An isActive parameter on groups. The conditions belong to the entries, and a group without any active entry is already hidden. The parameter would only add the confusing case of an inactive group holding active entries.
  • A hardcoded Other group, or one created on the fly when it's missing. The Other group is a UI extension like the others, which is easier to maintain. Removing it is possible but unlikely, and dropping the ungrouped entries with a warning is the simplest guardrail.
  • Falling back to a flat list when a single group is displayed. The gain is negligible and supporting both renderings would add a lot of complexity.
  • Groups that expand independently of each other. The menu matches the behaviour of the administration menu instead.
  • Extracting the administration accordion and migrating the administration menu to it. The administration accordion is local to XWiki.AdminSheet and comes with a search box. The new macro is generic, and migrating the administration menu to it can be done separately.
  • Fixing the typo in the entry extension point id. It would break every extension contributing to the menu.
  • Opening pull requests on the extensions outside the platform. Their entries show up in the Other group until they declare a group, and the extensions to update are listed on the issue with a suggested group for each.

Follow-ups

  • Ask the maintainers of the extensions listed on XWIKI-22065 to declare a group.
  • Document the new extension point and the group parameter.
  • Consider migrating the administration menu to the shared accordion macro.
  • Consider splitting the Preferences pane.

 

Get Connected