"attachmentSelector" Macro
Reference
Description
The attachmentSelector macro binds a picker to an xobject property holding a string: the reader picks one of the Page's attachments, and the macro writes that attachment's name into the property. It is how a sheet asks for a file, such as the photo on a user profile or the logo of a theme.
In view mode the macro prints the name of the attachment, or the image itself when the attachment is an image and displayImage is set.
In edit mode it also renders a button that opens the selector: a gallery of the Page's attachments, from which the reader selects one, uploads a new one, replaces or deletes an existing one, or empties the property.
With savemode="form", an attachment uploaded from the selector is held as a temporary attachment and written to the Page only when the form around the macro is saved, which is why the selector marks those attachments with a clock icon.
Use the attachmentGalleryPicker macro instead when there is no property to bind to: it searches the attachments of every Page through the search index and reports the reader's choice to a script.
Usage
{{attachmentSelector classname="Space.Page" property="propertyName"/}}
{{attachmentSelector classname="Space.Page" property="propertyName" object="0"/}}
{{attachmentSelector classname="Space.Page" property="propertyName" filter="pdf,odt"/}}
{{attachmentSelector classname="Space.Page" property="propertyName" displayImage="true"/}}
{{attachmentSelector classname="Space.Page" property="propertyName" savemode="direct"/}}The macro takes no content, and it works inline as well as on its own line. Its visibility is "Current Wiki", so it is available only in the wiki the Attachment Application is installed on.
Parameters
| Name | Mandatory | Allowed Values | Default Value | Description |
|---|---|---|---|---|
| classname | yes | A document reference | none | The Page holding the XClass whose property this picker edits. |
| property | yes | A property name | none | The property the picker writes the attachment name into. |
| object | no | An object number | The first object of classname on the Page | Which object the property belongs to, when the Page carries several of that class. |
| cssClass | no | A CSS class name | none | Set on the element surrounding the displayed value. |
| savemode | no | form, direct | form | How the property is updated. form stores the selected value in an input that an enclosing form saves; direct makes the picker save the property itself. |
| buttontext | no | Any text | The xe.attachmentSelector.selectFile translation | Text of the button that opens the selector. |
| defaultValue | no | An attachment reference | none | What view mode shows while the property is empty, written as photo.png for an attachment of the same Page or [email protected] for one of another Page. |
| filter | no | A comma-separated list of file extensions | none | Restricts the gallery to attachments with those extensions. Every attachment is accepted when it is empty. |
| displayImage | no | true, false | false | Whether an image attachment is shown as the image itself rather than as its name. |
| width | no | A length in pixels | none | Width of the displayed image. Read only with displayImage="true". |
| height | no | A length in pixels | none | Height of the displayed image. Read only with displayImage="true". |
| alternateText | no | Any text | none | The alt attribute of the displayed image. Read only with displayImage="true". |
| link | no | true, false | false | Whether view mode wraps the displayed name or image in a link to the attachment. |
| targetdocname | no | A document reference | The current Page | The Page whose attachments the gallery lists. |
| versionSummary | no | true, false | false | Whether the reader may type a version summary to record in the Page history. An automatic message is used when none is given. |
Examples
Ask for an Image
The photo on a user profile is asked for this way: the picker displays the image itself, and falls back to a default avatar while the property is empty.
{{attachmentSelector classname="XWiki.XWikiUsers" property="avatar" savemode="direct"
displayImage="true" width="180" filter="png,jpg,jpeg,gif"
defaultValue="[email protected]"/}}
Ask for a Document
Without displayImage, the picker shows the name of the attachment, linked here to the file itself.
{{attachmentSelector classname="Sandbox.AttachmentSelectorDemo" property="handbook"
filter="pdf,odt" link="true"/}}
Upload Without Saving the Page Yet
A picker inside a form uses savemode="form", the default, so that a file the reader uploads and then abandons is never written to the Page.
{{attachmentSelector classname="Sandbox.AttachmentSelectorDemo" property="handbook"
savemode="form"/}}
