|
| Description: |
The Edit Macro dialog of the code, container, gallery and menu macros shows the fields in alphabetical order, so the parameter that every example sets comes last, and the styling parameters are shown with the main ones.
The macros to change, with the file where most of the fix is done:
* code: parameters declared in [CodeMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-code/src/main/java/org/xwiki/rendering/macro/code/CodeMacroParameters.java].
* container: parameters declared in [ContainerMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-container/src/main/java/org/xwiki/rendering/macro/container/ContainerMacroParameters.java].
* gallery: parameters declared in [GalleryMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-gallery/src/main/java/org/xwiki/rendering/macro/gallery/GalleryMacroParameters.java].
* menu: parameters declared in its wiki macro definition, [MenuMacro.xml|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-menu/xwiki-platform-menu-ui/src/main/resources/Menu/MenuMacro.xml].
The main problems:
* The main parameter, language for code, layoutStyle for container and type for menu, comes after the others because the fields are sorted alphabetically.
* The cssClass, class and id styling parameters are not marked as advanced.
* code shows an image field inherited from the Box macro, which no example sets, and container opens with no layout while every example uses columns.
h2. KOs covered
||Macro||Criterion||Parameters||Problem||
|[code|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/code/]|C5 groups|{{cssClass}}, {{image}}, {{layout}}, {{source}}, {{title}}, {{width}}|The 8 fields, content included, are all in the single group "Optional parameters", above 7. The same holds for every parameter.|
|[code|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/code/]|C8 advanced|{{cssClass}}|A styling parameter that is rarely used, and no common example sets it, but it is not marked as advanced.|
|[code|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/code/]|C9 technical|{{image}}|Inherited from box, and no example sets it: users do not expect an image on a code block, so the field is only noise in the dialog and should be hidden for this macro.|
|[code|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/code/]|C6 order|{{language}}|Language is the only parameter set in the most common example, but it comes fourth, after Content, CssClass and Image, in alphabetical order.|
|[container|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/container/]|C8 advanced|{{cssClass}}|A styling parameter that is rarely used, and no common example sets it, but it is not marked as advanced.|
|[container|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/container/]|C3 defaults|{{layoutStyle}}|The most common example sets layoutStyle="columns", but the field opens empty, with no default value.|
|[container|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/container/]|C6 order|{{layoutStyle}}|The parameters are in alphabetical order, cssClass, justify, layoutStyle. layoutStyle, the only parameter of the most common example, comes last.|
|[gallery|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/gallery/]|C8 advanced|{{class}}|A styling parameter that is rarely used, and no common example sets it, but it is not marked as advanced.|
|[menu|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/menu/]|C6 order|{{type}}|The fields are in alphabetical order, Id, Label, Type. type, the only parameter of the most common example, comes last.|
|[menu|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/menu/]|C8 advanced|{{id}}|A parameter for JavaScript code and functional tests, rarely used, which is not marked as advanced.|
|[container|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/container/]|I2 zero-config|{{layoutStyle}}|Inserted with the default values and a content, the container applies no layout, since layoutStyle has no default. Partly covered, see below.|
h2. Impact found on macro fluidity
These 15 16 KOs come from the [WYSIWYG usability audit of the macros|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/], under the criteria C3 defaults, C5 groups, C6 order, C8 advanced, C9 technical , I2 zero-config of its [usability criteria|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Usability%20criteria/]. The page of each macro, linked in the table, has the full notes and the steps to reproduce. Fixing them means changing the parameter declarations of the macros: their groups, order, default values, mandatory and advanced flags.
The I2 zero-config KO of container is only partly covered here, for the missing default layout. The same KO also reports that the empty container shows nothing, covered by XWIKI-25567. |
|
