Macro Configuration Standards | UI/UX

​Hello everyone! :hugs: I come with a proposal for some rules for the UI/UX of the macro configuration modals. I tried to keep here the most general ones. Many fields are affected by these rules.

Goal of this standardization:

  • improve UX of macros, make them easier to use even by new users
  • keep everything consistent
    • make current configurations adhere to this standards
    • follow these standards in future development

1 Label naming

The label of a field should:

  1. try to be short
  2. try to make an additional description unnecessary
  3. try to not refer to the type of input, but to what the field represents for the configuration the user is doing
  4. try to not duplicate information: if something is understood by context, then it shouldn’t be specified in the name

2 Field description

The description of a field should mainly be reserved to:

  • linking to a section of documentation
  • providing concise instructions for how to use a new or custom UI.
  • specifying accepted file formats

Also, for anything that would not be known to a new user, there should be added a link in the description of the field. See examples in full page

The documentation could be provided…

  • externally - needing internet access
  • locally - as an extension (to be confirmed if this is possible, I don’t know the technicalities of it)

3 All fields should have a placeholder text

The placeholder should concisely say what the user should enter in a specific input box. Also, we should make sure it has enough color contrast, without making the normal text and the placeholder the same.

4 The length of the input box should indicate the length of the input needed.

We can have 3 general lengths (small input, medium input, big input) for large screens and the default length for small screens.

5 Selection method

Depending on the data that is contained in a list, selecting from that list can function differently.

The component that lists the options depends on the type of list we have:

  • a short limited list (with a maximum of 10 items at all times, is probably a static list)

    • UI component: dropdown with all options, non-searchable
    • example: the columns/properties that a livedata can have, layout types for a livedata
  • long limited list (dynamic list, with items that don’t need to be presented in a complex structure / hierarchy)

    • UI component: searchable dropdown (non-filterable, default sorting)
    • examples: the users an instance has, the tags of a wiki, the ids of usable livetables
  • unlimited list (dynamic list with a very high possible number of items that need to be presented / selected in a complex way)

    • UI component example: for pages, attachments → link dialog UI inspired
    • example: all pages in a wiki, attachments → they need trees, they can be refferenced or linked

6 Multi choice fields

= fields in which the user can enter multiple options

The user should NOT be required to input them without any help and only by delimiting the options with a column.

We should use a multi-option suggest input.

7 Singular choice field

= fields in which the user can choose only ONE option

If the choices are complicated in meaning, but can be explained in 1-2 lines of text…

  • …those explanations should be included in the dropdown (as it was done for quick actions).

If they can’t be explained in only 1-2 lines…

  • … a link must be provided concisely in the description of the field to let the user understand the differences between the choices

8 Checkbox field (true or false)

The label of a checkbox much be short but clear in its meaning, without it needing a description under the checkbox. The description is NOT forbidden; there are many cases in which the field label would be way too big if the field doesn’t rely on the description.

The label of a checkbox should specify…

  • what is affected by the check (a feature, an object, etc.)
  • and how does the check translate as an action upon the affected.

See examples in full page

9 Measurement fields

Fields that specify width or height or time until something happens should have two inputs:

  • one is the number,
  • the other one is a dropdown for the accepted units (px, percentage, em, rem, seconds, hour, etc.).

10 Code fields

For fields that require the user to input code (of any language) or wiki syntax or markdown, the field should have a different look than other normal text input fields.

See special cases who fall in this category + exceptions + look proposal in full page

11 CSS fields

= fields that let the user add new CSS or a CSS class to a certain macro

#1 The input should be formatted like a code field (with the default language CSS).

#2 This input should contain commented CSS code that shows the user what classes he can use for that specific macro and how.

#3 The field’s description should link to how to use CSS classes in XWiki or how to find the CSS class of a macro.

#4 Also, a link to examples would be nice.

12 Wiki syntax fields

For fields that require the user to input wiki sintax:

  • description should link to a guide on how to write wiki syntax correctly
  • the input box should contain a commented / not-outputted example of wiki syntax for that specific macro. For some macros, we can decide if this example should not be commented and just be the default value for that macro’s content.
  • they should be formatted like code fields

13 Page reference fields

For fields that require the user to reference a page/attachment/image/video we should use their dedicated selector component.
For fields that require multiple types, we can reuse the link dialog UI component.

For images & videos, we should add a functionality to only search through supported file types.

14 Alternative to referencing/selecting a file

Whenever the user can select/choose/reference/search a file, he should also be able to upload the file.


  1. Which rules do you agree with?
  2. Which should we edit?
  3. What do you think are the next steps after confirming the rules?

You give two examples and I don’t like / agree with neither of them.

  • “Wikis to display activity for” (versus “Wikis”) is definitely not short (the first criteria you listed)
  • “Page to include” (versus “Reference”): maybe the reason the parameter was named Reference is that it supports more than pages (e.g. you could pass an attachment reference). If the parameter supports only page references then I’d name the parameter simply “Page” because the macro name provides context of how that parameter is used. If I insert an “Include” macro and I see a “Page” parameter I understand from the context that it’s the page to include. I don’t think we need to “duplicate” this information in the parameter name, unless the way that parameter is used by the macro is not obvious.

linking to a section of documentation

Which documentation? The online documentation ( is not always available (e.g. for XWiki instances installed offline, behind a firewall) and it’s only in English, while the user may see the XWiki UI in a different language, e.g. French. The local (offline) documentation (provided by the Help application) is very limited also.

Are you suggesting applying custom CSS styles to the default HTML text input placeholder, using ::placeholder - CSS: Cascading Style Sheets | MDN ? What’s wrong with the default style provided by the browser?

I’m not convinced that it’s always possible / easy to know the expected input length, especially for text input. For number-based values it may be fine (unless the number format depends on the locale, in which case it’s not always easy to know how many dots or commas might be needed). And there’s also the fact that the macro edit modal width could be smaller on mobile devices, so if you’re planing to use a percent, say 30% for small input, then that will be too small on a mobile device (unless you also set a minimum width, but to which value?)

Also note that the content of the macro edit modal is generated from the macro descriptor, so you need a way for the macro (parameter) descriptor to say something like “I’d like this parameter to be edited with a small input but not less than 10 characters”.

It’s not clear to me the difference between “long limited list” and “unlimited list”. I’d use a suggest input for both.

An add button (+) must be present after the component that lists the options

I don’t like this part. What’s wrong with a suggest input that allows multiple selection? Like the user picker (edit a group to see). It has no plus / add button, but I haven’t heard users complaining about it. You need to take into account also the limited space available in the macro edit modal. If the label of the selected values is not too large then a widget like the multi-select suggest input which displays the selected values one after another (inline) is good enough for me.

It’s not clear if you suggest to never put a description under the checkbox or to only try to avoid it. I think sometimes the description is needed / useful, so I wouldn’t forbid it. If I had to choose between a long label without hint and the short label with hint I’d probably prefer the latter.

If the macro supports multiple units, which is not always the case.

description should link to a guide on how to write wiki syntax correctly

Again, the question is where is that guide stored (local XWiki instance versus and whether it is translated in the user locale or just English.

You mean for macro parameters that support references to different entity types right? I mean a macro parameter that can take as input both a page reference and an attachment reference. Otherwise, if the macro parameter supports a single entity type then I don’t see why we should use a complex widget like the one from the link dialog, when we can simply use a page picker, or an attachment picker, i.e. a dedicated picker.


1 Like

There will be a lot of cases in which not all criteria can be met.
As I formulated the “rules” for this, one should TRY to adhere to them.

No description > slightly longer field name

I feel like it’s better to have a slightly longer field name rather than provide a description for a simple field.

A description for me is necessary if there is a high enough risk that the title might not provide enough context and, thus, confuse the user. By this thinking, if every field has a description, it inspires a high level of complexity.


In the following picture, I may have not chosen the shortest or even the best field names, but, altogether, the configuration still feels much less complex than the initial one.

I agree with that. I will modify the rule to capture this idea too.

Yes, I was referring to the only good option we have right now, which is I know it’s not always available for some cases, but I strongly believe it is much better to have it still.

Right now, we don’t offer any help to people that just want some quick example of usages for basic macros.

They still have to search it on the internet and have a slight distrust in the quality of their search. Should we just let them continue with that when we could be of help to a lot of our users with pretty little effort?

An alternative to using an external link, would be to have the documentation as part of an extension.

About the language: english documentation easily available is a better documentation than a hard-to-find documentation or none at all.

So, I’ve searched for a placeholder text in XWiki and the quickest I found was this one:

To me, the difference between the textbox with text in it and the textbox with only placeholder text in it is very minimal and would like a more obvious way to show that. It is a subjective thing and would need a bit more feedback on this. We can continue with the default styling if everyone feels like it’s not a big deal. @tkrieck wdyt?

we could use these 3 sizes only for big screens and let all inouts be the same length on small screens.

Okay, thanks for the feedback. The multi-select suggest input with no + button could prove to be the better option.

I mean to try to avoid it. There are many cases in which the name would be way too big without a description to explain it, so forbidding it would be a bad call, indeed.

From what I’ve looked into, all width and height fields let the user input px and percentages, at least.

Time fields should allow multiple units, if they don’t.

Okay, I think I formulated the point a bit rough
For single enitity type → dedicated picker, for multiple types → link dialog component

I will come back on this with an actual visual example, but the main difference is that in a long limited list you don’t need to allow the user to search through trees for example and you most probably won’t need to paste a refference or link to the options. It’s just that selecting pages or attachements is a bit more complex

Edited my initial post to include @mflorea 's feedback

A little bit of differentiation would not hurt, at least to separate user input content vs automated ones. Gmail for example, have a very subtle variation that I think is quite good.

Screenshot 2024-07-09 at 13.48.03
Screenshot 2024-07-09 at 13.42.45
User text
Screenshot 2024-07-09 at 13.43.08

MacOS on the other hand gives much more emphasis between the two states

Screenshot 2024-07-09 at 13.44.59
User text
Screenshot 2024-07-09 at 13.45.32

But all in all, if we give the placeholder a more subtle color, it should follow the WCAG contrast rules and not go too light on the color.

I agree with linking to the docs, because even if some users do use XWiki fully offline, most I’d presume have an internet connection (and we don’t really do anything in this regard for fully offline people atm anyway). It would also push us to improve the documentation (I’m trying to look through it in between other stuff).

Fully agree here. Having users manually type some text in a box when all the valid options are predefined is just bad UX. It was one of the first things I noticed while trying XWiki and one of the first things I disliked.

It would be a usability improvement, however I’m struggling to imagine a way in which two text boxes next to each other would look good.

I think everything else you mentioned would still be improvements, but more subtle ones.