Attachment Selector Macro

Version 22.1 by Ramona Conoro on 2015/04/30 13:53

photosA picker associated with XObject properties of type String, which offers a friendly UI for selecting one of the document's attachments and putting its name in the property's value
TypeXAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Enterprise Manager

Compatibility

2.5+, bundled since 3.0

Installable with the Extension Manager

Description

The Attachment Selector is a picker associated with XObject properties of type String, which offers a friendly UI for selecting one of the document's attachments and updating the property's value with that attachment's name.

In view mode, it displays the name of the attachment or the corresponding image if the attachment is an image and the macro is parametrized to display images, possibly surrounded by a link to the attachment if the link parameter is set to true.
In edit mode, it also generates a button that triggers the actual selector. The selector consists of an attachment gallery listing the attachments of the current document that are accepted by the property (see the filter parameter), and giving the possibility to upload new attachments, to select or delete existing attachments, and to empty the property value.

Usage examples

{{attachmentSelector classname="Sandbox.Demo" property="attachedDocument" filter="pdf,odt"/}}

{{attachmentSelector classname="Sandbox.Demo" property="attachedImage" filter="png,jpg,gif"
displayImage="true"/}}

{{attachmentSelector classname="XWiki.XWikiUsers" property="avatar" savemode="direct"
displayImage="true"  width="120" link="true" filter="png,jpg,gif"
defaultValue="[email protected]"/}}

Parameters

  • classname (mandatory): The full name of the document holding the XClass that contains the property associated with this picker.
  • property (mandatory): The name of the property associated with the picker.
  • object: The identifier (number) of the object for which the property is displayed by this picker. If missing, the first instance of the class given by the parameter classname found in the document will be considered.
  • cssClass: A CSS class for the element surrounding the displayed property value.
  • savemode: States how the property is updated. Accepted values: form (default) meaning that the selected value is stored in an input that will be saved via an external form; direct means that the picker is responsible with updating the property value.
  • buttontext: Text of the button that triggers the picker. Defaults to $services.localization.render('xe.attachmentSelector.selectFile').
  • defaultValue: What attachment is displayed in view mode if the property is empty. Should either be empty or in the form of a wiki attachment reference (e.g.: attachment.txt, [email protected]).
  • filter: Comma separated list of file extensions accepted by the property (to become a comma separated list of mimetypes when XWiki will use HTML5). All files are accepted if this parameter is empty.
  • displayImage: States whether images are displayed or just their name is printed like for other attachments. Possible values: true, false (default).
  • width: The width of the displayed image, only taken into account if displayImage="true".
  • height: The height of the displayed image, only taken into account if displayImage="true".
  • alternateText: The alternate text (alt attribute) of the displayed image, only taken into account if displayImage="true".
  • link: States whether a link to the attachment is associated in view mode with the displayed attachment name/image. Possible values: true, false (default).
  • targetdocname: An optional reference to a document to use as the source (and target) for the attachments to display. By default the current document is used.

Screenshots

chooseimage.png

choosefile.png

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

After importing the XAR, register the translations document Macros.AttachmentSelectorTranslations in the Internationalization Document Bundles field of the Programming section of the wiki administration.

The xar contains a slightly modified version of the Lightbox extension.

    

Get Connected