| 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. 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.
KOs covered
| Macro |
Criterion |
Parameter |
Problem |
| 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 |
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 |
C5 groups |
image |
One more field among the main parameters of the dialog, for a value that a code block does not need. |
| 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. |
Impact found on macro fluidity These 4 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, C4 input-assistance, C5 groups and C9 technical of its usability criteria. 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. |
