Reference

Description

The attachmentGalleryPicker macro displays a search field and a grid of the attachments it finds, from which the reader picks one. It is the building block for a form that asks for an attachment: an image to illustrate an entry, a document to link from an application. In the macro list of the editors it appears as "Attachment Picker", in the "Development" category.

Each result shows the name of the attachment under a preview of it: the image itself when the attachment is one, the icon of its media type otherwise. When the reader searches every Page, the attachments of the current Page are listed first. InformationThe results come from the search index. An attachment that has not been indexed yet is not among them.

The reader chooses where to search: in the current Page only, or in every Page they are allowed to view. Picking an attachment that does not belong to the current Page displays a warning, because an application storing that reference keeps it pointing at the other Page.

To ask for an attachment from a form rather than from a grid, use the Suggest Attachments widget, which turns a text input into an attachment suggester, or the attachmentSelector macro, which writes the choice into an xobject property.

Usage

{{attachmentGalleryPicker/}}

{{attachmentGalleryPicker id="myid"/}}

{{attachmentGalleryPicker filter="image/*"/}}

{{attachmentGalleryPicker limit="5"/}}

{{attachmentGalleryPicker target="Space.Page"/}}

The macro takes no content, and works standalone only: written inside a paragraph it reports an error instead of rendering the picker.

Give the macro an id when the surrounding application has to know which picker it is talking to: the id is set on the element the macro renders, which is how a script reaches this picker among several, and how it listens to the selection events described below.

Parameters

Examples

Pick Any Attachment of the Wiki

Without a parameter, the picker searches every attachment the reader is allowed to see.

{{attachmentGalleryPicker/}}

Pick an Image

A form asking for an illustration accepts images only. The filter is applied to the media type of the attachment, so image/* keeps every image format.

{{attachmentGalleryPicker id="illustration" filter="image/*"/}}

A filter matching nothing leaves the grid empty, and the picker says so rather than showing an empty area:

Pick a Document

An attachment that is not an image is shown with the icon of its media type instead of a preview.

{{attachmentGalleryPicker filter="application/pdf,text/plain" limit="5"/}}

Pick From Another Page

An application editing one Page from another needs the picker to work on the Page being edited, not on the Page carrying the form. The target parameter says which one that is, and the "current page" scope and the warning then follow it.

{{attachmentGalleryPicker target="Sandbox.WebHome"/}}

React to the Selection From JavaScript

The picker reports what the reader does through two events, sent on the element the macro renders:

Give the macro an id and listen on it:

{{attachmentGalleryPicker id="myid"/}}

require(['jquery'], function($) {
  // Selects the picker by the id given to the macro.
  const picker = $('#myid');

  picker.on('xwiki:attachmentGalleryPicker:selected', function(event, attachmentReference) {
    // Store or display the reference of the attachment the reader picked.
  });

  picker.on('xwiki:attachmentGalleryPicker:unselected', function() {
    // React to the reader clearing their selection.
  });
});

Related

• Attachments
• Suggest Attachments Widget
• "attachmentSelector" Macro