attachmentSelector
Audit
- Macro ID
- attachmentSelector
- Source
- XS
- Type
- Generator
- Classification reason
- The macro has no content: its output is the attachment stored in an object property, read from the page and its parameters, and the button that picks it, so it is classified as a generator.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- attachmentGalleryPicker useravatar
Sources
Where to gather the information the criteria are checked against, see Gather the sources.
| Other sources specific to this macro |
|---|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | KO | minor: "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. Its French name, "Sélecteur de pièce jointe", differs by one letter from the one of Attachment Picker, "Sélecteur de pièces jointes", which both show for the French search. |
| D2 summary | KO | 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. To reproduce: open the Insert Macro dialog and select Attachment Selector. |
| D3 category | OK | Development, like the compared macro attachmentGalleryPicker, the other attachment widget for applications. useravatar is in Content, where users look for an avatar, which does not apply to a macro that needs an XClass and a property. |
| D4 quick-action | KO | Quick Actions finds the macro first for "attachmentSelector", "Attachment Selector" and "attachment", second for "upload", after Image, and first for the French name "Sélecteur de pièce jointe". The synonyms "file", "file picker" and "pick file" give no result. Quick Actions also lists "Sélecteur de pièces jointes" for the French search, which is the name of Attachment Picker, not a second entry for this macro. The fr translations keep the English ID as the name of 10 parameters and leave the description of versionSummary in English, which is a note for a developer macro, not a KO. |
| L1 consistency | OK | compared with attachmentGalleryPicker and useravatar, two generators with no content. Like useravatar, the Quick Action opens the Edit Macro dialog since classname and property are mandatory, whereas attachmentGalleryPicker has no mandatory parameter and is inserted right away. The mandatory pair is by design: the macro writes the choice into an object property, which the picker does not. |
| L2 doc-parameters | OK | the new documentation lists the 15 parameters with the same mandatory flags and defaults as the macro, and states the defaults that the macro leaves undeclared: the first object for object, the translation of xe.attachmentSelector.selectFile for buttontext and the current page for targetdocname. |
| L3 doc-example | OK | the Usage block of the documentation only holds templates with the placeholders Space.Page and propertyName, so the most common example is the first example of the Examples section, "Ask for an Image", which is also the avatar call of the user profile in XWiki Standard: {{attachmentSelector classname="XWiki.XWikiUsers" property="avatar" savemode="direct" displayImage="true" width="180" filter="png,jpg,jpeg,gif" defaultValue="[email protected]"/}} . It renders without error, and all 4 documented examples do. It renders something only on a page that holds an object of the class, which the introduction states. |
| I1 pattern | OK | compared with children, the reference generator, and useravatar. From Quick Actions and from the Insert Macro dialog, the Edit Macro dialog opens with the focus on classname, the generic behavior of a generator with a mandatory parameter. Only one Quick Actions entry inserts the macro. |
| I2 zero-config | OK | submitting the Edit Macro dialog with an empty classname keeps it open with no message, the generic behavior of the dialog. {{attachmentSelector/}} in view mode gives "Parameter [classname] is mandatory", which names the parameter. With a valid class and property, the editor shows the button "Choose an attachment", and view mode shows the attachment name, or nothing while the property is empty, which is the expected display of an empty value. |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | classname and property, the two mandatory fields, come first above the Optional parameters tab, are visible without scrolling, and classname has the focus. |
| E1 wysiwyg | OK | with the example above, on a page holding an object of a test class, the editor and view mode show the same 180 pixel picture and the same "Choose an attachment" button. With the default savemode="form", view mode shows only the name of the attachment while the editor adds the button and a hidden input: this is a dedicated edit representation that keeps the meaning of the macro, which the documentation describes, so it does not fail E1. |
| E2 errors | KO | invalid values are accepted silently, with no message. {{attachmentSelector classname="MacroAudit.NoSuchPage" property="attachment"/}} , classname="a b c" and property="nosuchprop" display nothing. object="abc" silently shows the first object, and object="-3" or object="99" show nothing. savemode="DIRECT", savemode="maybe" and savemode="Form" behave as form. displayImage="maybe", link="maybe" and versionSummary="maybe" behave as false. displayImage="true" width="abc", width="-3", width="0" and height="abc" are output as the width and height of the image. defaultValue="no spaces allowed here" shows that text as the attachment name while the property is empty, and a missing attachment, defaultValue="[email protected]", shows its name with no link. targetdocname="MacroAudit.NoSuchPage" displays nothing. filter="pdf odt" and filter="pdf" are accepted. Only a missing classname gives a message that names the parameter. |
| E3 nesting | OK | in a list item, a table cell and a box, the macro renders its name and the button, in the editor and in view mode, with no error, like at the top level of the page. |
| E4 inline-support | KO | the macro declares inline support but its output is a block. Before {{attachmentSelector classname="..." property="attachment"/}} after. renders <p>Before <p><span class="displayed">name</span></p> after.</p>, a paragraph inside a paragraph that breaks the line, and with savemode="direct" the output is a div that holds a paragraph and the button, so the sentence is split in both cases. |
| E5 empty | N/A | |
| E6 inplace | N/A |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| classname | OK | OK | N/A | KO | OK | OK | N/A | OK | OK | OK | C4, minor: a page picker that offers every page, where only pages holding an XClass are useful, and the XClass of the example, XWiki.XWikiUsers, is a page the user has to know. C13: the page picker builds a valid reference, so the dialog does not need to reject a typed value. |
| property | OK | OK | N/A | KO | OK | OK | N/A | OK | OK | KO | C4: a plain text field for the name of a property of the chosen class, where a select of the properties of that class could be used. For example, typing "nosuchprop" is accepted and the macro displays nothing. C13, minor: the name of a property declares no format, so the dialog accepts property="a b" and the macro displays nothing, with no message. |
| object | OK | OK | OK | KO | KO | OK | N/A | KO | OK | KO | C4: a plain text field for the number of an object, where a number field could be used. For example, typing "abc" is accepted and the macro silently uses the first object. C8: an object number is needed only on a page that carries several objects of the class, which the examples of XWiki Standard never do, and the parameter is not advanced. C13, minor: object is a string with no declared range, so object="-3" and object="99" are accepted and display nothing. |
| cssClass | OK | OK | OK | OK | KO | OK | N/A | KO | OK | N/A | C8: a styling hook that no example sets, not marked advanced. |
| savemode | OK | OK | OK | KO | KO | KO | N/A | OK | OK | N/A | C3: form is the declared default and the value that most XWiki Standard sheets use, the theme and skin sheets, so it is preselected. The most common example sets direct, like the user profile. C4: a plain text field prefilled with "form" for a choice between the two values form and direct, where a select could be used. For example, typing "maybe" is accepted and behaves as form. C6: the example sets it, and it switches between the two uses of the macro, but the dialog sorts the fields alphabetically and shows it below the fold, after the fields filter, height, link and object. |
| buttontext | KO | OK | OK | OK | KO | OK | N/A | KO | OK | N/A | C1: 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". C8: the label of the button is changed now and then, and the parameter is not advanced. |
| defaultValue | OK | OK | OK | OK | KO | OK | N/A | OK | OK | OK | C4: an attachment picker, which was not checked for the attachments it lists. |
| filter | KO | OK | OK | KO | KO | KO | N/A | OK | OK | KO | C1, minor: 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". C3: empty means every file, which the description says, and no single value is used in most cases. C4: a plain text field for a comma separated list of file extensions, where a field that offers the common file types could be used. For example, typing "pdf odt" or "pdf" is accepted. C6: the example sets it, but the dialog shows it below the fold. C13, minor: the list of extensions declares no format, so the dialog accepts any text. |
| displayImage | OK | OK | KO | OK | KO | OK | N/A | OK | OK | OK | C3, minor: the checkbox opens unchecked, while the most common example and every use of XWiki Standard that shows an image set displayImage="true". |
| width | KO | OK | OK | KO | KO | KO | N/A | OK | OK | KO | C1, minor: the description gives no unit, and the documentation says a length in pixels, so a user cannot tell whether "180px" or "50%" works. C4: a plain text field for a number of pixels, where a number field could be used. For example, typing "abc" is accepted and output as width="abc". C6: the example sets it, but the dialog shows it below the fold, last of the optional fields. C13: the width declares no range, so width="-3" and width="0" are accepted and output as is. |
| height | KO | OK | OK | KO | KO | OK | N/A | KO | OK | KO | C1, minor: the description gives no unit, like width. C4: a plain text field for a number of pixels, where a number field could be used. For example, typing "abc" is accepted and output as height="abc". C8, minor: set rarely, since the examples set the width only, and not advanced. C13: the height declares no range, like width. |
| alternateText | OK | OK | OK | OK | KO | OK | N/A | KO | OK | N/A | C8, minor: set now and then, only for an image, and not advanced. It comes first in the dialog, before the fields of the example. |
| link | OK | OK | OK | OK | KO | OK | N/A | KO | OK | OK | C8, minor: used in one documented example, and not advanced. |
| targetdocname | OK | OK | OK | OK | KO | OK | N/A | KO | OK | OK | C1: the description, "The target page name to save/list attachments from", is accurate: the gallery lists and uploads on that page, while the property stays on the current page, which only the documentation says. C8: set rarely, and not advanced. |
| versionSummary | OK | OK | OK | OK | KO | OK | N/A | KO | OK | OK | C8: asks for a history comment, set rarely, and not advanced. |
Other notes
Other notes: the macro is a developer building block, audited as a developer macro because of its Development category. Bugs outside the criteria, to file in JIRA: in savemode="direct" the button "Choose an attachment" is shown in view mode to anonymous visitors, who cannot edit the page, since the macro tests only the view right of the target page and never uses the edit right it computes. The description of buttontext shows the unrendered text $services.localization.render('xe.attachmentSelector.selectFile') in the dialog, in every language. An invalid parameter on the example page renders nothing, which leaves a developer with no hint.
KOs and tickets
Every KO needs a ticket covering it, see Report the KOs. One ticket can cover several KOs. Known issues filed for this macro are suggested in italics: link them as existing tickets when they cover the KO.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| D1 | D1 wording | XWIKI-25473 | |
| D2 | D2 summary | XWIKI-25473 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25581 (partial) | |
| E4 | E4 inline-support | XWIKI-25577 | |
| C4:classname | C4 input-assistance, classname | XWIKI-25559 | |
| C4:property | C4 input-assistance, property | XWIKI-23045 (partial) | XWIKI-25499 |
| C13:property | C13 constraints, property | XWIKI-25197 | |
| C4:object | C4 input-assistance, object | XWIKI-23037 | |
| C5:object | C5 groups, object | XWIKI-25474 | |
| C8:object | C8 advanced, object | XWIKI-25474 | |
| C13:object | C13 constraints, object | XWIKI-25197 | |
| C5:cssClass | C5 groups, cssClass | XWIKI-25474 | |
| C8:cssClass | C8 advanced, cssClass | XWIKI-25474 | |
| C4:savemode | C4 input-assistance, savemode | XWIKI-23038 | |
| C5:savemode | C5 groups, savemode | XWIKI-25474 | |
| C6:savemode | C6 order, savemode | XWIKI-25474 | |
| C1:buttontext | C1 clarity, buttontext | XWIKI-25473 | |
| C5:buttontext | C5 groups, buttontext | XWIKI-25474 | |
| C8:buttontext | C8 advanced, buttontext | XWIKI-25474 | |
| C5:defaultValue | C5 groups, defaultValue | XWIKI-23039 | |
| C1:filter | C1 clarity, filter | XWIKI-25473 | |
| C4:filter | C4 input-assistance, filter | XWIKI-23045 (partial) | XWIKI-25499 |
| C5:filter | C5 groups, filter | XWIKI-25474 | |
| C6:filter | C6 order, filter | XWIKI-25474 | |
| C13:filter | C13 constraints, filter | XWIKI-25197 | |
| C3:displayImage | C3 defaults, displayImage | XWIKI-25474 | |
| C5:displayImage | C5 groups, displayImage | XWIKI-25474 | |
| C1:width | C1 clarity, width | XWIKI-25473 | |
| C4:width | C4 input-assistance, width | XWIKI-25197 (partial), XWIKI-25182 (partial) | XWIKI-25499 |
| C5:width | C5 groups, width | XWIKI-25474 | |
| C6:width | C6 order, width | XWIKI-25474 | |
| C13:width | C13 constraints, width | XWIKI-25197 | |
| C1:height | C1 clarity, height | XWIKI-25473 | |
| C4:height | C4 input-assistance, height | XWIKI-25197 (partial), XWIKI-25182 (partial) | XWIKI-25499 |
| C5:height | C5 groups, height | XWIKI-25474 | |
| C8:height | C8 advanced, height | XWIKI-25474 | |
| C13:height | C13 constraints, height | XWIKI-25197 | |
| C5:alternateText | C5 groups, alternateText | XWIKI-25474 | |
| C8:alternateText | C8 advanced, alternateText | XWIKI-25474 | |
| C5:link | C5 groups, link | XWIKI-25474 | |
| C8:link | C8 advanced, link | XWIKI-25474 | |
| C5:targetdocname | C5 groups, targetdocname | XWIKI-25474 | |
| C8:targetdocname | C8 advanced, targetdocname | XWIKI-25474 | |
| C5:versionSummary | C5 groups, versionSummary | XWIKI-25474 | |
| C8:versionSummary | C8 advanced, versionSummary | XWIKI-25474 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-23037 | Existing | C4:object | |
| XWIKI-23038 | Existing | C4:savemode | |
| XWIKI-23039 | Existing | C5:defaultValue | |
| XWIKI-25197 | Existing | C13:filter C13:height C13:object C13:property C13:width | C4:width C4:height |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| XWIKI-25444 | New | D4 | |
| XWIKI-25473 | New | C1:buttontext C1:filter C1:height C1:width D1 D2 | |
| XWIKI-25474 | New | C3:displayImage C5:alternateText C5:buttontext C5:cssClass C5:displayImage C5:filter C5:height C5:link C5:targetdocname C5:versionSummary C5:width C6:filter C6:savemode C6:width C8:alternateText C8:buttontext C8:cssClass C8:height C8:link C8:object C8:targetdocname C8:versionSummary C5:object C5:savemode | |
| XWIKI-23045 | Existing | C4:filter C4:property | |
| XWIKI-25182 | Existing | C4:width C4:height | |
| XWIKI-25499 | New | C4:width C4:height C4:filter C4:property | |
| XWIKI-25559 | New | C4:classname | |
| XWIKI-25577 | New | E4 | |
| XWIKI-25581 | New | E2 |
Known issues of this macro
| Issue | Title | Status | Criteria |
|---|---|---|---|
| XWIKI-23037 | AttachmentSelector macro Editor: The picker for the property `object` should be more specific | Open | C4 |
| XWIKI-23038 | AttachmentSelector macro Editor: The picker for the property `savemode` should be more specific | Open | C4 |
| XWIKI-23039 | AttachmentSelector macro Editor: The picker for the property `defaultValue` should be more specific | Open | C4 |
68 more known issues affect every macro: see the Known issues.
Lucas Charpentier