|
| Description: |
The code macro has an image parameter only because it reuses the box macro: {{CodeMacro}} extends {{AbstractBoxMacro}}, and {{CodeMacroParameters}} extends {{BoxMacroParameters}}, to get the frame and the title of the box. The image of a box makes no sense on a code block, no example of the documentation sets it, yet the Edit Macro dialog shows it in the main parameters, described as "the image which is to be displayed in the message box".
The parameters are 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].
h2. Proposal
* Override {{getImage()}} and {{setImage()}} in {{CodeMacroParameters}} and annotate them with {{@Deprecated}}, which marks the parameter as deprecated in the descriptor of the code macro only: the box and message macros keep it.
* The Edit Macro dialog then hides the field when the macro does not set it, and shows it as deprecated when an existing macro does, so the pages that use it keep their image and their users can still remove it.
h2. KOs covered
||Macro||Criterion||Parameter||Problem||
|[code|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/code/]|C1 clarity|{{image}}|"The image which is to be displayed in the message box" calls the code block a message box, and does not say whether an attachment or a URL is expected.|
|[code|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/code/]|C4 input-assistance|{{image}}|A free text field, with no image picker, although the type is a resource reference: a reference to a missing attachment is accepted.|
|[code|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/code/]|C5 groups|{{image}}|One more field among the main parameters of the dialog, for a value that a code block does not need.|
|[code|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/code/]|C9 technical|{{image}}|Inherited from box, and set by no example: users do not expect an image on a code block, so the field is only noise in the dialog.|
|[code|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/code/]|E2 errors|{{image}}|image="missing.png" renders a broken image, with no message. Deprecating the parameter removes it from the dialog. Partly covered, see below.|
h2. Impact found on macro fluidity
These 4 5 KOs come from the [WYSIWYG usability audit of the macros|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Macros/], under the criteria C1 clarity, C4 input-assistance, C5 groups and , C9 technical and E2 errors of its [usability criteria|https://design.xwiki.org/xwiki/bin/view/Proposal/WYSIWYGusabilityofXWikimacros/Usability%20criteria/]. The page of the macro, linked in the table, has the full notes. Deprecating the parameter covers them all, since the field leaves the dialog.
The E2 errors KO of code is only partly covered here, for the image. The same KO also reports other invalid values, covered by the other issues listed on the page of the macro, among them XCOMMONS-3847 for the conversion of the values and XRENDERING-823 for the wording of the error. |
|
