Description

Last updates and agreed upon conclusions

Macro Configuration  

#1 A field that has a limited list of possible values, should offer the user those values before selection (through any available UI) - made JIRA issue

#2 We should start linking documentation in macros even if that documentation is in english, even if it’s not always available. It is a step forward and will be of a lot of help to users. We don’t need to make everything perfect from the first time.

#3 Slightly more spacing between each property would be nice.

Macro block appearance and behaviour

#4 On hover, next to the move icon, we’d display an edit icon button and the name of the macro. JIRA Issue

#5 For the issue of differentiating macro boundary and content boundary: I think it highly depends on color contrast or just general accessibility:

• choose a different colour for content boundary (maybe main color or link color, if it has enough contrast in all cases)

or

• use a dashed line for macro boundary

#6 Empty macros render the “macro: content“ message. It’s good, but we could make it much nicer easily.

• add more padding (especially vertical)
• some round corners (by radius variable)
• add a light gray background (by color variable)
• instead of “macro: content“ just write “Empty macro. Use the edit icon or double click to configure it.“

Initial proposal

UI/UX rules  based on current & improved modal configs

You can see in this linked section improved modal configs for several macros.

You can see here all current macro modal configs.

Based on these, we can extract certain UI/UX rules:

# 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

Example for point 2: Don’t name the field “Wikis”, name it “Wikis to display activity for”. This way the user doesn’t need to read the description to get it, we can just delete the description, making the interface cleaner at the same time. This can't be done for all fields, in some cases, the label would become way too long.

Example for point 3: It's wrong to name a field "Reference" just because the user needs to input a page reference. The field could be renamed as "Page to include" - it specifies what the field represents - a page - and it briefly says why it's needed - to be included in current context.

# Field length

The length of the field should indicate the length of the input needed.

Example: For a number input field we don’t need to have a field that is 1/4 of the whole screen width.

# 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

• 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

# Multi choice field

For fields in which the user can enter multiple options, the user shouldn’t be required to input them without any help and by delimiting the options with a column.

Why? This method requires the user to know beforehand all possible/compatible/accepted options and then to input them correctly.

Solution: The UI should let the user see/extend/search through all possible options and let the user add/check/choose the options he wants. For users used to entering multiple options by entering a column, this possibility should also be present

UI implementation: An add button  must pe present after the component that lists the option. 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).

# 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 usr understand the differances between the choices

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

Example: "Drag & drop" as a label specify only the feature which is affected by the check, but doesn't say what the check will do to tht feature. A better lable would be "Enable drag & drop for moving nodes"

Example: Currently, there is a checkbox field with label: “RSS” and the description “Whether to show activity RSS link or not.”. This whole UI could’ve been a checkbox with the label “Show activity RSS link”

# Field description goal

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.

Examples: getting a page refference, getting the translation key of an extension, getting an extension’s ID, writing in wiki syntax a table, writing a query, writing JSON, etc.

# More category - limited usage *

The More category should stop being used in the cases in which it only contains a maximum of 5 fields and the fields are not that advanced in their usage.

The items that are not used so often, but are not that hard to be used should appear by themselves outside of the More category, but collapsed.

# Flagging advanced fields *

Advanced or niche fields should be flagged us such, with the text “(advanced)” after the field’s label.

Again, as per my previous point, not all fields in the More category are advanced fields.

# Filter/Sort fields in liveData configurations *

For filtering/sorting a liveData table inside the configuration modal…

• we should use the Filter/Sort UI we have outside the modal
• or we should NOT have filtering/sorting inside the modal and only let the user filter in the page, not in the modal config

# Technical terminology in labels *

The filter’s label or description must try to not use technical terminology.

Example: target

Exception to this rule is considered to be any seperate clearly defined UI that uses that terminology and offers the info easily to the user.

Exception to this rule is also considered any advanced field that bases its UX on the highly technical knowledge of the user.

Exception example: the page refference. While it uses a technical sounding terminology, there is a seperate UI (in the Page information tab) that offers this data to the user in a dirrect manner. Thus, we can use “page refference” in the label or description of a field in modal configuration.

What to use instead of target?  Just specify who/what is affected: “User to display pages from”, “Page to display macros from”

# Measurement fields

Fields that specify width or height should have two inputs:

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

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

• one is the number,
• the other one is a dropfown for the accepted units (seconds, minutes, hours, days, etc.).

# Wiki syntax fields

For fields that require the user to input wiki sintax:

• the description of the field should link to a quide on how to write wiki syntax correctly in general.
• the input field should contain a commented / not-outputed example of wiki syntax for that specific macro. For some macros, we can decide if that content should not be commented and just be the default value for that macro’s content.
• their UI style should be the same with the one for code fields

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

Fields that require the user to input the HTML id fall in this category, also.

Fields that require the user to input an extension ID, macro ID or other xwiki components' IDs do NOT fall in this category. They should ideally be singular choice fields (the user can select them from a list of all available extension IDs/macro ID/etc.), but if this is not feasible to implement, they should just be simple text fields.

UI style for code fields (proposal):

• #fafafa background color
• text should be in a typewriter/mono font,
• if the language is defined, the code should have syntax highlighting for that language.

# Placeholder text

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

# Paste value signaling (nice to have)

Fields that require using the page refference or another value that could be copyed from another UI:

• must provide a paste button
• have the placeholder text specify that they can paste or enter that specific value.

# Date input fields *

Fields that require a date should:

• provide an UI for selecting a date from a calendar
• or provide a dirrectly formatted UI for inputting the date in the needed format.

Example: if we don’t want the user to select a date from a calendar, we can provide a UI like: [placeholder text: day] / [placeholder text: month] / [placholder text:year]

# Page refference fields

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

For images & videos, we should add one more category in the selector to only search through supported file types.

# CSS fields

For fields that let the user add new css to a certain macro, the input should be formatted like a code macro with the default language CSS, as per point #13.

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

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

Also, a link to examples would be nice.

# Alternative to refferencing/selecting file

Whenever there is a field where you have to specify the file/image/doc/attachment, there should also be the option to upload that specific thing. Sometimes you just don’t want to refference it.

# Signaling the default option *

The default option should be signaled as default with the text “(default)” following the option name, in light italic.

# Section refference field *

For fields that require the user to provide a section id, a list of possible headings to choose from that certain page should be made available to the user.

The user shouldn't need to go to the other page, search through the headings and figure out how to format the id to make sure it works.

# Consistent terminology *

Terminology specific to XWiki should be consistent. Do not use gadgets for macros, or spaces for wikis.

Macro config improvements

• #1 Container macro
• #2 Dashboard
•  #3 Gallery
• #4 Include Page
• #5 Async macro
•  #6 Chart
• #7 Content Macro
• #8 Display
• #9 Footnote
• #10 Icon
•  #11  Live data
• #12 Office document viewer
• #13 Pages

#1 Container macro

Opens blank? Yes ✅
Issues of the current modal UI for the Container macro:	Improvements:
Confusing explanation under CSS class I have no idea what to enter in the field of CSS class The CSS class field should provide an example, a commented one at least that doesn't affect the code until it's taken out of comments - even as an advanced user, I wouldn't know where to take the classes from, even based on the docs Not very necessary explanation under Justify Field of Layout style should be a dropdown - Default option should be signalled as default in the dropdown Content is the most important field - why is it in the More category? Because Content uses xwiki syntax, it needs to provide a basic example (like in the official documentation The field for content contains code, so it should have UI style / formatting that reflects that	make macro title bold shorten description of macro dropdown selector for Layout style if there is selector, no need for description on Layout Style no need for description on Justify content inside container take Content out of the More category, bring it after Justify content change content title into Add your content have link to writing wiki syntax correctly have the input field for any type of code be light gray have some content example written in wiki syntax remove the More category & keep anything that would’ve been in the More category as expandable in this case, CSS styling should expandable, not by default opened as it’s a slightly advanced use case have link on how to get the class of the column have link to some common CSS code for the Container macro input field to have some default CSS example have more room between each field/section
Before & after of the modal

#2 Dashboard

Opens blank? Yes ✅
Issues of the current modal UI for the Container macro:	Improvements:
gadgets shouldn't be used as a term for macros Layout's field should be a dropdown - columns should be signalled as a default option in this dropdown no need for explanation under Layout style (it doesn't help in nay way) Source label has a vague name, you really have to read the explanation to understand Source's field should be a dropdown - "Current page" should be signalled as default option in the dropdown Style has 2 functions: specify a default style or a custom style by actually adding custom CSS code - this duality makes what to put in the field confusing (i m scared of entering anything cause there is a high probability of failing) Style should have an example of custom CSS code Style should also have a dropdown for plain and panels	make macro title bold get rid of the term “gadgets” dropdown selector for Layout style if there is selector, no need for description on Layout Style make Source title more explicit, no need for description dropdown selector for Source make Style title more explicit, no need for description dropdown selector for Style new field/section for custom CSS have the input field for any type of code be light gray in this case, Add custom CSS styling should expandable, not by default opened as it’s a slightly advanced use case have link on how to get the class of the contents have link to some common CSS code for the Dashboard macro input field to have some default CSS example commented to define what happens with rendering style if you add custom CSS, does it get deleted or is the base on which is added the custom CSS have more room between each field/section
Before & after of the modal

 #3 Gallery

Opens blank? Yes, in editor. ✔ Once saved and in view, if empty, has an empty gallery look.
Issues of the current modal UI for the Container macro:	Improvements:
gallery content doesn't provide example of how to include images, hard to do without a direct link to a documentation custom CSS doesn't provide an example of CSS for this gallery height and width don't provide info about the unit in which the number entered will be inputs don't have placeholders width shouldn't really be in the More category	make macro title bold simplify macro description change Content into Add your images simplify explanation under Add your images add syntax code example commented in the field for adding images change Class into Add custom CSS styling improve explanation add CSS example commented Gallery height should have one input field for a number and a dropdown selector for the unit (px, rem, em) same for width width shouldn’t be in the More category, it doesn’t make the modal that much longer
Before & after of the modal

#4 Include Page

Opens blank? No, it opens directly in a modal config.
Issues of the current modal UI for the Container macro:	Improvements:
there is a high change the user doesn't how to get the refference I see section as an actually common usecase for this macro, shouldn't be in the More category or collapsed user doesn't know how to get a section's ID I see exclude heading 1 as a common usecase, shouldn't be in the more category or collapsed Author has misleading name - it's not really about the author but more about how the page is executed right? there's no way anyone would know what the options to author mean	make macro title bold change plural to singular in macro description change Page into “The page to include” add link to how to obtain a pge’s refference simplify  wording on first heading exclusion change Section to “Include only a specific section” add link to how to obtain a section ID change Author to Execution based on author, mark it as advanced add link to how to understand the options mark Auto as default option
Before & after of the modal

#5 Async macro

Opens blank? No, it opens directly in a modal config.
Issues of the current modal UI for the Container macro:	Improvements:
maybe the user is yet not used to wiki syntax even if async macro is a more technical macro	make macro title bold add link to how to write wiki sintax add code look to the input field for context no need for the descriptions for Async or Chache mark context as advanced add an explanation for why would one need to add context add link to how to modify the context mark id overriden with advanced add an explanation for why would one need to add context add link to how to add custom iD
Before & after of the modal

 #6 Chart

Opens blank? No, it opens directly in a modal config.

Issues of the current modal UI for the Container macro:

maybe the user is yet not used to wiki syntax even if async macro is a more technical macro

Before & after of the modal

#7 Content Macro

Opens blank? Well, yes, but it makes sense it does. You can directly start writing on that line and when just clicking on the row the user is invited to use quick actions.
Issues of the current modal UI for the Container macro:	Improvements:
Before & after of the modal

#8 Display

#9 Footnote

Bugged, can't be used on its own.

#10 Icon

Opens blank? No, it opens directly in a modal config

Issues of the current modal UI for the Container macro:

Before & after of the modal

 #11  Live data

Opens blank? Not really, but it doesn't have data in it so it's kind of blank kinda not. The three dots on its right don't
Issues of the current modal UI for the Container macro:	Improvements
Before & after of the modal

#12 Office document viewer

Opens blank? No, it opens in an error box.
Issues of the current modal UI for the Container macro:	Improvements
Before & after of the modal

#13 Pages

Opens blank? No, it opens in a live table. Should be changed to live data

Issues of the current modal UI for the Container macro:

Before & after of the modal