Details
-
Improvement
-
Resolution: Unresolved
-
Major
-
None
-
17.10.14, 18.8.0
-
None
-
Unknown
-
Description
The names and descriptions of the attachmentGalleryPicker and attachmentSelector macros, and of their parameters, are what the Insert Macro and Edit Macro dialogs show to explain them. Both macros are building blocks for applications, but their plain names suggest a picker a user can insert in a page, and several descriptions miss what to type.
The macros to change, with the file where most of the fix is done:
- attachmentGalleryPicker: defined in AttachmentGalleryPickerMacro.java, descriptions in ApplicationResources.properties.
- attachmentSelector: defined in AttachmentSelector.xml, descriptions in ApplicationResources.properties.
The main problems:
- Neither the names nor the descriptions say that the macros are meant to be wired to an application: Attachment Picker only sends a JavaScript event, and Attachment Selector binds a picker to an object property.
- The description of attachmentSelector is about 60 words long, and the description of its buttontext parameter shows an unrendered Velocity call.
- The width, height and filter parameters give no unit or example value.
KOs covered
| Macro | Criterion | Parameters | Problem |
|---|---|---|---|
| attachmentGalleryPicker | D1 wording | "Attachment Picker" uses plain words, but the macro is a developer building block: inserted in a page on its own, it shows a search field and a grid of attachments, and picking one only sends a JavaScript event, it inserts or links nothing. | |
| attachmentGalleryPicker | D2 summary | "Grid based attachment picker." repeats the name and does not say what the macro adds to the page: a search field with Current Page and All Pages scopes and a grid of attachments to pick from, meant to be wired to an application by JavaScript. | |
| attachmentGalleryPicker | C1 clarity | id | "The id of the attachment picker macro" does not say what the id is for: it is set as the HTML id of the rendered element, so that a script can reach the picker and listen to its selection events, which only the documentation says. |
| attachmentSelector | D1 wording | "Attachment Selector" uses plain words, but the macro is a developer building block that binds a picker to an object property. A user who types "attachment" to add an attachment to the page gets it first in Quick Actions, before Attachment Picker, another developer widget, and no entry that adds an attachment comes before them, the decision taken for attachmentGalleryPicker. | |
| attachmentSelector | D2 summary | The description has four sentences and about 60 words, where the measure says about 20 or fewer, and it speaks of "object properties of the current page that are supposed to contain the name of an attachment". It does not say that the macro also displays the chosen attachment, or its image, in view mode. | |
| attachmentSelector | C1 clarity | buttontext | The description ends with the unrendered text "Defaults to $services.localization.render('xe.attachmentSelector.selectFile')" in the dialog, in English, French and German, instead of the text of the default button, "Choose an attachment". |
| attachmentSelector | C1 clarity | filter | The description gives no example value and keeps an outdated remark, "to become a comma separated list of mimetypes when XWiki will use HTML5", so the user cannot tell whether to write "pdf" or ".pdf". |
| attachmentSelector | C1 clarity | width | The description gives no unit, and the documentation says a length in pixels, so a user cannot tell whether "180px" or "50%" works. |
| attachmentSelector | C1 clarity | height | The description gives no unit, like width. |
Impact found on macro fluidity
These 9 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, D1 wording, D2 summary of its usability criteria. The page of each macro, linked in the table, has the full notes and the steps to reproduce. Fixing them means changing the translations of the macros and, for a name or a category, their definitions.