|
| Description: |
The Edit Macro dialog of the script macros shows the rarely used jars and wiki parameters with the main ones, and keeps a parameter that is required, or not needed, the same as the others.
The macros to change, with the file where most of the fix is done:
* velocity: parameters declared in [VelocityMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-velocity/src/main/java/org/xwiki/rendering/macro/velocity/VelocityMacroParameters.java].
* groovy: parameters declared in [JSR223ScriptMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-script/src/main/java/org/xwiki/rendering/macro/script/JSR223ScriptMacroParameters.java].
* python: parameters declared in [JSR223ScriptMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-script/src/main/java/org/xwiki/rendering/macro/script/JSR223ScriptMacroParameters.java].
* script: parameters declared in [DefaultScriptMacroParameters.java|https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-script/src/main/java/org/xwiki/rendering/macro/script/DefaultScriptMacroParameters.java].
The main problems:
* The jars and wiki parameters, which no documented example sets, are not marked as advanced on the four macros.
* The language parameter of the Script macro should be mandatory: without it the script is not run.
* The jars parameter of the Velocity macro, inherited from the script macros, should be hidden , which also removes a list field with no declared separator from its dialog .
h2. KOs covered
||Macro||Criterion||Parameters||Problem||
|[groovy|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/groovy/]|C8 advanced|{{jars}}|A rarely used parameter, set by no example of the documentation and none of the XWiki Standard calls found, and not marked as advanced.|
|[groovy|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/groovy/]|C8 advanced|{{wiki}}|Wiki="false" is a realistic but rare use, set by no example of the documentation, and the field is not marked as advanced.|
|[python|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/python/]|C8 advanced|{{jars}}|A rarely used parameter, set by no example of the documentation and by no XWiki Standard call, and not marked as advanced.|
|[python|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/python/]|C8 advanced|{{wiki}}|Wiki="false" is a realistic but rare use, for a script that outputs text with wiki characters, and the field is not marked as advanced. Recorded like wiki of velocity and groovy.|
|[script|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/script/]|C8 advanced|{{jars}}|A rarely used parameter, set by no example of the documentation, and it is not marked as advanced.|
|[script|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/script/]|C2 mandatory|{{language}}|The macro cannot do anything without it: with no language the script is not run and its source is rendered as plain text, see I5. It should be mandatory, so this is a KO.|
|[script|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/script/]|C8 advanced|{{wiki}}|Wiki="false" is a realistic but rare use, for a script that outputs text with wiki characters, and the field is not marked as advanced. Recorded like wiki of velocity.|
|[velocity|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/velocity/]|C8 advanced|{{filter}}|A rarely used parameter, no example of the common use sets it and none of the XWiki Standard calls found sets it, but it is not marked as advanced.|
|[velocity|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/velocity/]|C8 advanced|{{jars}}|A rarely used parameter, not set by any example nor by the XWiki Standard calls found, and not marked as advanced.|
|[velocity|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/velocity/]|C9 technical|{{jars}}|Inherited from the script macros and not documented for velocity: a user does not expect to add JARs to the class loader of a Velocity script, which is mostly a groovy need, so the field is only noise in the dialog.|
|[velocity|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/velocity/]| C13 constraints|{{jars}}|A list of references with the separator undeclared: "a.jar, b.jar" is refused with "Failed to add JAR URLs to the current class loader". Hiding the parameter removes the field.|
|[velocity|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/velocity/]| C8 advanced|{{wiki}}|Wiki="false" is a realistic but rare use, found once in the XWiki Standard calls, and the field is not marked as advanced.|
h2. Impact found on macro fluidity
These 11 12 KOs come from the [WYSIWYG usability audit of the macros|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/], under the criteria C2 mandatory, C8 advanced, C9 technical , C13 constraints 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. |
|
