attachmentSelector

Last modified by Lucas Charpentier on 2026/10/27 10:27

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.

SourceWhat it givesUsed forWhere
DocumentationParameters, default values and examples, including the most common exampleL2, L3, and the criteria measured with the most common examplehttps://www.xwiki.org/xwiki/bin/view/documentation/xs/dev/attachments/attachmentselector-macro/
Source codeHow the macro declares its parameters and content: types, groups, features, advanced and hidden flags, constraints, content type, inline supportC4, C5, C7, C8, C9, C13, E4, E6https://github.com/xwiki/xwiki-platform/blob/xwiki-platform-18.8.0/xwiki-platform-core/xwiki-platform-attachment/xwiki-platform-attachment-ui/src/main/resources/XWiki/AttachmentSelector.xml
Macro descriptorWhat the Edit Macro dialog is built from, on design.xwiki.orgD1, D2, C1 to C9, E4Descriptor, list of macros with their categories
TranslationsThe name, description and parameter names in each languageD1, D2, D4, C1l10n.xwiki.org
Uses in XWiki pagesHow XWiki itself uses the macro, a realistic example when the documentation has noneL3, C2, C3, C6, C8, C9Search the xwiki organization on GitHub
Compared macrosThe audits of the macros of the same typeL1, D3attachmentGalleryPicker, useravatar
Other sources specific to this macro
CriterionResultNotes
D1 wordingKOminor: "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 summaryKOthe 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 categoryOKDevelopment, 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-actionKOQuick 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 consistencyOKcompared 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-parametersOKthe 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-exampleOKthe 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 patternOKcompared 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-configOKsubmitting 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 instantN/A
I4 cursorN/A
I5 focusOKclassname and property, the two mandatory fields, come first above the Optional parameters tab, are visible without scrolling, and classname has the focus.
E1 wysiwygOKwith 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 errorsKOinvalid 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 nestingOKin 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-supportKOthe 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 emptyN/A
E6 inplaceN/A

Parameters

ParameterC1 clarityC2 mandatoryC3 defaultsC4 input-assistanceC5 groupsC6 orderC7 alternativesC8 advancedC9 technicalC13 constraintsNotes
classnameOKOKN/AKOOKOKN/AOKOKOK

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.

propertyOKOKN/AKOOKOKN/AOKOKKO

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.

objectOKOKOKKOKOOKN/AKOOKKO

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.

cssClassOKOKOKOKKOOKN/AKOOKN/A

C8: a styling hook that no example sets, not marked advanced.

savemodeOKOKOKKOKOKON/AOKOKN/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.

buttontextKOOKOKOKKOOKN/AKOOKN/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.

defaultValueOKOKOKOKKOOKN/AOKOKOK

C4: an attachment picker, which was not checked for the attachments it lists.

filterKOOKOKKOKOKON/AOKOKKO

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.

displayImageOKOKKOOKKOOKN/AOKOKOK

C3, minor: the checkbox opens unchecked, while the most common example and every use of XWiki Standard that shows an image set displayImage="true".

widthKOOKOKKOKOKON/AOKOKKO

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.

heightKOOKOKKOKOOKN/AKOOKKO

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.

alternateTextOKOKOKOKKOOKN/AKOOKN/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.

linkOKOKOKOKKOOKN/AKOOKOK

C8, minor: used in one documented example, and not advanced.

targetdocnameOKOKOKOKKOOKN/AKOOKOK

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.

versionSummaryOKOKOKOKKOOKN/AKOOKOK

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.

KOCriterionExisting ticketsNew tickets
D1D1 wordingXWIKI-25473
D2D2 summaryXWIKI-25473
D4D4 quick-actionXWIKI-25444
E2E2 errorsXCOMMONS-3847 (partial), XRENDERING-823 (partial), XWIKI-25581 (partial)
E4E4 inline-supportXWIKI-25577
C4:classnameC4 input-assistance, classnameXWIKI-25559
C4:propertyC4 input-assistance, propertyXWIKI-23045 (partial)XWIKI-25499
C13:propertyC13 constraints, propertyXWIKI-25197
C4:objectC4 input-assistance, objectXWIKI-23037
C5:objectC5 groups, objectXWIKI-25474
C8:objectC8 advanced, objectXWIKI-25474
C13:objectC13 constraints, objectXWIKI-25197
C5:cssClassC5 groups, cssClassXWIKI-25474
C8:cssClassC8 advanced, cssClassXWIKI-25474
C4:savemodeC4 input-assistance, savemodeXWIKI-23038
C5:savemodeC5 groups, savemodeXWIKI-25474
C6:savemodeC6 order, savemodeXWIKI-25474
C1:buttontextC1 clarity, buttontextXWIKI-25473
C5:buttontextC5 groups, buttontextXWIKI-25474
C8:buttontextC8 advanced, buttontextXWIKI-25474
C5:defaultValueC5 groups, defaultValueXWIKI-23039
C1:filterC1 clarity, filterXWIKI-25473
C4:filterC4 input-assistance, filterXWIKI-23045 (partial)XWIKI-25499
C5:filterC5 groups, filterXWIKI-25474
C6:filterC6 order, filterXWIKI-25474
C13:filterC13 constraints, filterXWIKI-25197
C3:displayImageC3 defaults, displayImageXWIKI-25474
C5:displayImageC5 groups, displayImageXWIKI-25474
C1:widthC1 clarity, widthXWIKI-25473
C4:widthC4 input-assistance, widthXWIKI-25197 (partial), XWIKI-25182 (partial)XWIKI-25499
C5:widthC5 groups, widthXWIKI-25474
C6:widthC6 order, widthXWIKI-25474
C13:widthC13 constraints, widthXWIKI-25197
C1:heightC1 clarity, heightXWIKI-25473
C4:heightC4 input-assistance, heightXWIKI-25197 (partial), XWIKI-25182 (partial)XWIKI-25499
C5:heightC5 groups, heightXWIKI-25474
C8:heightC8 advanced, heightXWIKI-25474
C13:heightC13 constraints, heightXWIKI-25197
C5:alternateTextC5 groups, alternateTextXWIKI-25474
C8:alternateTextC8 advanced, alternateTextXWIKI-25474
C5:linkC5 groups, linkXWIKI-25474
C8:linkC8 advanced, linkXWIKI-25474
C5:targetdocnameC5 groups, targetdocnameXWIKI-25474
C8:targetdocnameC8 advanced, targetdocnameXWIKI-25474
C5:versionSummaryC5 groups, versionSummaryXWIKI-25474
C8:versionSummaryC8 advanced, versionSummaryXWIKI-25474
Success

Every KO is covered by a ticket.

Tickets

TicketOriginKOs coveredKOs partly covered
XWIKI-23037ExistingC4:object
XWIKI-23038ExistingC4:savemode
XWIKI-23039ExistingC5:defaultValue
XWIKI-25197ExistingC13:filter C13:height C13:object C13:property C13:widthC4:width C4:height
XCOMMONS-3847NewE2
XRENDERING-823NewE2
XWIKI-25444NewD4
XWIKI-25473NewC1:buttontext C1:filter C1:height C1:width D1 D2
XWIKI-25474NewC3: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-23045ExistingC4:filter C4:property
XWIKI-25182ExistingC4:width C4:height
XWIKI-25499NewC4:width C4:height C4:filter C4:property
XWIKI-25559NewC4:classname
XWIKI-25577NewE4
XWIKI-25581NewE2

Known issues of this macro

IssueTitleStatusCriteria
XWIKI-23037AttachmentSelector macro Editor: The picker for the property `object` should be more specificOpenC4
XWIKI-23038AttachmentSelector macro Editor: The picker for the property `savemode` should be more specificOpenC4
XWIKI-23039AttachmentSelector macro Editor: The picker for the property `defaultValue` should be more specificOpenC4

68 more known issues affect every macro: see the Known issues.

Get Connected