Macro config UI

[tkrieck]

Hi everyone,

Macros are one of the main and most used features of XWiki. In conversations with @surli, we identified a number of pain points in the current macro configuration interface, and I’d like to take this opportunity to propose a potential solution.

Note:
This post serves as a companion to the following discussions:

• https://forum.xwiki.org/t/macro-configuration-standards-ui-ux/14965
• https://forum.xwiki.org/t/macro-integration-ux-proposal/16732

Usability Issues with the Current Macro UI (Configuration Dialog)

• Only a limited number of fields are shown by default
• Inconsistent design patterns that diverge from XWiki’s UI/UX standards (labels, notably)
• The “More” button is too small and easily overlooked
• The ordering of fields is inconsistent—prioritized by recent usage but still capped at three visible fields
• The macro name and description resemble input fields, which can be misleading
• Some required fields are grouped in mutually exclusive sets, but this logic isn’t clearly conveyed to users

Principles to Guide the redesign

• Required fields should be immediately visible
• Field order should remain consistent, regardless of configuration
• Mutually exclusive fields should be clearly marked, with user-driven toggles
• The overall form should be as compact as possible
• Modified fields should be visually distinguishable to the user

Proposed Solution

• A new layout that distinctly separates introductory text from input fields
• Required fields are at the top of the interface and never hidden.
• Eliminate the “More” button entirely
• Introduce a tabbed interface to separate optional fields and reduce vertical length

Simple Example: Box Macro

Current UI:

Box Macro with the proposed layout

I reorganized the fields a bit to put the more used ones on top, but this work should be done in a case-by-case scenario.

More Complex Scenario

Here’s a sample scenario drafted by @surli to illustrate more intricate configurations:

• Parameter1 – Mandatory
• Parameter2 – Mandatory
• Parameter3 – Part of Mandatory Feature1
• Parameter4 – Part of Mandatory Feature1
• Parameter5 – Optional
• Parameter6 – Optional, part of Group1
• Parameter7 – Optional, part of Group1
• Parameter8 – Part of Optional Feature2
• Parameter9 – Part of Optional Feature2

Here’s how the modal configuration dialog might appear:

Yes—it’s complex, but still manageable. This represents a worst-case scenario, helping us evaluate the robustness of the UI rules. Some of the improvements:

Explicit Control for Mutually Exclusive Options

Tabbed Groups for Optional Fields and Features

Change Indicators on Modified Tabs

---

This approach aims to bring clarity and consistency into the macro configuration experience, I’m looking forward to your thoughts and feedback. If needed, I can propose different scenarios based on these rules.

Thank you all for reading.

[surli]

Thanks for your work on this!

@tkrieck

Here’s how the modal configuration dialog might appear:

There’s something I don’t get: why the “Optional input” before the tabs is not in “Others” in this screenshot? AFAIR the idea was that when we have tabs we’d put everything which is not grouped in this “Others” tab no? else what’s its purpose?

[gabrielc]

Hi Thiago! Thanks for working on this!

I really like the new designs. My only feedback would be that, as Adina stated in point 5 of her proposal, I think there should be multiple types of fields depending on the expected data.

For example, in the case of CSS Class, it would be fine to keep using a text field.

However, for content where we already know the expected values, for example the Image field, where we already know the images available on the page, I think the field should become a dropdown with the available items.
Same for other config options where we already know the values.

e.g.: The livedata macro has the layouts option that only takes table and cards as values. At the moment you need to input the words manually in a text field. I think it would be better to present the user with a dropdown from which they can choose either of the 2 available options.

@tkrieck

Required fields should be immediately visible

Agreed. I’d also add an indicator to let users know those fields are required. A simple * would suffice in my opinion.

[tkrieck]

@surli

There’s something I don’t get: why the “Optional input” before the tabs is not in “Others” in this screenshot? AFAIR the idea was that when we have tabs we’d put everything which is not grouped in this “Others” tab no? else what’s its purpose?

I fear to have scenarios in which we have a tab bar (so, at a minimum one Feature or Group and then the Other tab) but only one field in there, so I put it outside. IMO, if doable technically ofc, grouping lone fields under the “Other” tab could be decided in a case-by-case scenario.

@gabrielc

My only feedback would be that, as Adina stated in point 5 of her proposal, I think there should be multiple types of fields depending on the expected data.

You’re right. In my mocks I just copied the fields and paid more attention to the order of the fields, but I agree with that each field should, as much as possible, have its corresponding input type.

@gabrielc

Agreed. I’d also add an indicator to let users know those fields are required. A simple * would suffice in my opinion.

I put the string “required” on each, as it’s the current default o other XWiki forms. The asterisk would be a cleaner option (and universally used) but it should be standard across all XWiki. I checked, and it uses a CSS class called xRequired so perhaps it’s easily doable if that class is also used here.

Example on the create user form

Thanks for the input.