"Label" parameter for macros generating UI content

[CharpentierLucas]

Hello!
When working on XWIKI-19450: Several nav tags are used without aria-label, I thought about the need to add a label parameter to the Menu Macro.
The Menu Macro did already have an id parameter, but nothing close to a human readable label. In the context of this issue, the label would be used on the navigation element generated by the menu. The main purpose of this parameter is to give an accessible name to the menu bar, a navigation element. Accessible names can typically be set as attributes aria-label or title.

About aria-label:

A brief description of the purpose of the navigation, omitting the term “navigation”, as the screen reader will read both the role and the contents of the label.

from mdn web docs on the navigation landmark

Defines a string value that labels the current element.
[…]
It provides the user with a recognizable name of the object.

from WAI-ARIA 1.3

As we can see above, the definition of the attribute is not always completely equal to the way it’s supposed to be used in interfaces:

• WAI-ARIA: aria-label content is very similar to a name
• MDN: aria-label content is similar to a description

---

I think most macros that generate some UI content could use a label parameter to set as an accessible name for the element they generate.
I think label is a correct way to name it, because this name is as wide as its use might be: for some macros this label will be very close to a name, and for others it will be more similar to a short description of the functionality.
Some other names we could use for this parameter might be name or title.

What do you think of the name label for such Macro Parameters ?
Do you think we should make it a recommendation and update the Parameters section of the wiki Macro tutorial?

Thank you for reading and I’m looking forward to your feedback!

[vmassol]

@CharpentierLucas

Do you think we should make it a recommendation and update the Parameters section of the wiki Macro tutorial?

It wouldn’t be the right place for sure. This is only for wiki macros. If we were to define this as a best practice, it would need to go somewhere under Best Practices (XWiki.org) IMO (and links could be created to it from the macro tutorials, for ex from Writing a Macro (XWiki.org) ). The other way around is also acceptable. To be discussed but that’s a detail at this point.

@CharpentierLucas

I think most macros that generate some UI content could use a label parameter to set as an accessible name for the element they generate.

Why most? Do you see examples of macros that should not do this? What’s the rule?

@CharpentierLucas

I thought about the need to add a label parameter to the Menu Macro.

BTW I don’t see any <nav> HTML element at xwiki-platform/MenuMacro.xml at 22c2e56d0bbee53384ce59cbedc4dd50c60d1976 · xwiki/xwiki-platform · GitHub

Can you show me where it’s added?

This is important since a macro isn’t supposed to generate HTML but XDOM and we don’t have an equivalent to the <nav> HTML element in XDOM.

We’d need to decide if this parameter is for accessibility only or for other things.

Examples of macros that I can imagine also wanting to use such a parameter (not exhaustive):

• Gallery macro
• LiveTable/LiveData macros
• Container macro
• etc

Are there existing macros having such a parameter already?

Thx

[CharpentierLucas]

@vmassol

Why most? Do you see examples of macros that should not do this? What’s the rule?

Create unique names for elements with the same role unless the elements are actually identical. For example, ensure every link on a page has a different name except in cases where multiple links reference the same location.

From W3C accessible name practices
If a macro displays the same content, there is no need for the labels to be different from one element to the other (it would be a bit overzealous and quite difficult to find different labels anyways).
I couldn’t find one, but if there’s a macro without parameters or content that displays some interface, we can just use a fixed label for it and we don’t need to add a parameter.

---

@vmassol

BTW I don’t see any <nav> HTML element at xwiki-platform/MenuMacro.xml at 22c2e56d0bbee53384ce59cbedc4dd50c60d1976 · xwiki/xwiki-platform · GitHub

There is a div with role=“navigation”, which is semantically similar.

@vmassol

This is important since a macro isn’t supposed to generate HTML but XDOM and we don’t have an equivalent to the <nav> HTML element in XDOM.

Note that this would be better to replace it with a nav element, but it’s correct to use role if we can’t use the element itself

It is NOT RECOMMENDED for authors to set the ARIA role and aria-* attributes to values that match the implicit ARIA semantics defined in either table. Doing so is unnecessary and can potentially lead to unintended consequences.

From ARIA in HTML recommendation

@vmassol

We’d need to decide if this parameter is for accessibility only or for other things.

I think this parameter is mostly useful for accessibility but it’s just good practice to give a label to non-presentation elements (especially interactive ones) and it can improve usability. E.g. used with a title attribute, it can display some details on the macro content that might help all users.

@vmassol

Examples of macros that I can imagine also wanting to use such a parameter (not exhaustive):

• Gallery macro
• LiveTable/LiveData macros
• Container macro
• etc

Are there existing macros having such a parameter already?

• Gallery macro: class, height, width
• Livetable/Livedata macro: id, columns, columnsProperties, options (nothing about a label in options)
• Container macro: justify, layoutStyle, cssClass
• Panel macro: title

While looking at other macros, I didn’t find a name parameter so far, but only id and title. I didn’t go through every macro, but a fair bit and the title from Panels was the closest I found so far.