Macro Configuration Standards | UI/UX

[amilica]

​Hello everyone! 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.

---

Conclusions

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?
   ​

[mflorea]

@amilica

1 Label naming

The label of a field should:

1. try to be short
2. try to make an additional description unnecessary
3. not refer to the type of input, but to what the field represents for the configuration the user is doing

See examples in full page

---

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.

@amilica

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

linking to a section of documentation

Which documentation? The online documentation (xwiki.org) 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.

@amilica

3 All fields should have a placeholder text written in light italic.

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.

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?

@amilica

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).

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”.

@amilica

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

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

@amilica

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.

UI implementation: An add button (+) must be present after the component that lists the options. After entering one option, if the user clicks the (+) button or types a column, another option can be chosen from the component that lists the option (see previous rule).

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.

@amilica

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 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.

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.

@amilica

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.).

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

@amilica

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

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 xwiki.org) and whether it is translated in the user locale or just English.

@amilica

13 Page reference fields

For fields that require the user to reference a page/attachment/image/video we should reuse the page/attachment/link selector from the link feature.

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

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.

Thanks,
Marius

[amilica]

@mflorea

“Wikis to display activity for” (versus “Wikis”) is definitely not short (the first criteria you listed)

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.

Example

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.

@mflorea

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.

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

@mflorea

Which documentation? The online documentation (xwiki.org) 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.

Yes, I was referring to the only good option we have right now, which is xwiki.org. 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.

@mflorea

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?

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?

@mflorea

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?)

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

@mflorea

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.

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

@mflorea

It’s not clear if you suggest to never put a description under the checkbox or to only try to avoid it.

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.

@mflorea

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

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.

@mflorea

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.

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

@mflorea

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

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

[amilica]

Edited my initial post to include @mflorea 's feedback

[tkrieck]

@amilica

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?

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.

Resting

Focused

User text

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

Focused

User text

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.

[gabrielc]

@amilica

2 Field description

The description of a field should mainly be reserved to:

• linking to a section of documentation

I agree with linking to the xwiki.org 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).

@amilica

5 Selection method

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

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.

@amilica

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.).

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.

[mflorea]

@amilica

Your screenshot seems to suggest replacing the “Style” parameter which accepts as value a CSS class name with a new parameter that supports inline CSS styles? Injecting CSS styles inline, in the content, is bad. On the other hand a CSS class name can be semantic and changing the associated CSS styles can be done from a single place (the skin, the color theme, etc.) affecting the entire wiki, which ensures consistency.

I also noted that there is a “(page reference)” suffix styled differently for one of the macro parameter labels. Is that part of the macro label?

• Yes: then how does the macro dialog know to display it differently?
• No: what does it represent then? It can’t be the hint, as the hint is displayed below the label. Are you introducing a new concept? (that may have to be mapped to the macro parameter descriptor).

@amilica

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?

Have you seen xwiki-platform/xwiki-platform-core/xwiki-platform-flamingo/xwiki-platform-flamingo-skin/xwiki-platform-flamingo-skin-resources/src/main/resources/flamingo/less/variablesInit.vm at master · xwiki/xwiki-platform · GitHub ? Bootstrap already overwrites the placeholder style, and we overwrite the default Bootstrap color for the placeholder text.

Thanks,
Marius

[amilica]

@mflorea

Your screenshot seems to suggest replacing the “Style” parameter which accepts as value a CSS class name with a new parameter that supports inline CSS styles? Injecting CSS styles inline, in the content, is bad. On the other hand a CSS class name can be semantic and changing the associated CSS styles can be done from a single place (the skin, the color theme, etc.) affecting the entire wiki, which ensures consistency.

Okay, I understand what you are saying and I’m aware that inline styling is harmful, but it should be easy for a user to customize the look of a macro without going through several screens to do so. Maybe we could rethink this process as:

• user defines the class directly in the macro, but its definition is actually stored in the advanced property of the theme, while the true value of the macro field is only the classname
• whatever modification happens in advanced section it would happen in the whole instance (as it already does) and the class would get redefined in the macro too

If what I said makes sense, is this technically possible? If yes, would it take a long time to do this? Customizing macros would become much, much easier for people.

At the very least, we can just add a description to this kind of field that teaches the user how to define the class & where to define it. (I’ll modify the rules to fit this)

@mflorea

I also noted that there is a “(page reference)” suffix styled differently for one of the macro parameter labels. Is that part of the macro label?

• Yes: then how does the macro dialog know to display it differently?
• No: what does it represent then? It can’t be the hint, as the hint is displayed below the label. Are you introducing a new concept? (that may have to be mapped to the macro parameter descriptor).

The suffix is more of a nice-to-have to be honest. If this is too complicated to introduce as a new concept, we might be better off with just renaming the macro label and that’s it (no suffix).

This new concept would represent the former name of the label in case we changed it to better suit new users. Users that have a lot of history with XWiki may remember things very clearly by a name, so if we change it to better suit new users, old users might be confused. The suffix would help with that.

[mflorea]

@amilica

Okay, I understand what you are saying and I’m aware that inline styling is harmful, but it should be easy for a user to customize the look of a macro without going through several screens to do so. Maybe we could rethink this process as:

• user defines the class directly in the macro, but its definition is actually stored in the advanced property of the theme, while the true value of the macro field is only the classname
• whatever modification happens in advanced section it would happen in the whole instance (as it already does) and the class would get redefined in the macro too

If what I said makes sense, is this technically possible? If yes, would it take a long time to do this? Customizing macros would become much, much easier for people.

I’m not convinced by this. The user that inserts the macro is most often not an administrator of the wiki so they can’t take actions that affect the entire wiki (e.g. modify the color theme). The simplest to me is to have a suggest input / dropdown with some known values to chose from (the macro developer needs to provide this list), for simple users, but that also lets you type new values, for advanced users.

Thanks,
Marius