Reference

The RequireJS module xwiki-attachment-picker, one of the two modules of the Attachment Picker WebJar, turns markup into a working picker: it builds the search field, fills the grid of results, and reports what the reader picks.

Markup of a Picker

A picker is an element carrying the class attachmentGalleryPicker, holding four blocks that the JavaScript looks up inside it by class:

Three optional attributes on the root element configure it. The JavaScript only reads them, and they are the three parameters of the attachmentGalleryPicker macro:

The macro writes exactly that markup, but any markup carrying those classes works, once the module is loaded on the Page as described below:

<div class="attachmentGalleryPicker"
     data-xwiki-attachment-picker-filter="image/*"
     data-xwiki-attachment-picker-limit="10"
     data-xwiki-attachment-picker-target="Sandbox.WebHome">
  <div class="attachmentPickerSearch"></div>
  <div class="attachmentPickerResults"></div>
  <div class="attachmentPickerNoResults hidden">No attachment matches your search.</div>
  <div class="attachmentPickerGlobalSelection hidden">The attachment you picked belongs to another
    page.</div>
</div>

Initialisation

The module registers the jQuery plugin $.fn.attachmentGalleryPicker():

require(['jquery', 'xwiki-attachment-picker'], function ($) {
  // The module exports nothing: requiring it is what registers the plugin.
  $('#my-picker').attachmentGalleryPicker();
});

Results

Every result of a search is one attachmentGroup element:

<span class="attachmentGroup localAttachment">   <!-- jQuery data "id": the attachment reference -->
  <a title="logo.png" href="/xwiki/bin/download/Sandbox/WebHome/logo.png">
    <span class="previewWrapper">
      <img loading="lazy" alt="logo.png"
           src="/xwiki/bin/download/Sandbox/WebHome/logo.png?width=150&height=150&keepAspectRatio=true">
    </span>
    <span class="attachmentTitle" title="logo.png">logo.png</span>
  </a>
</span>

While a search runs, the results block is emptied and carries the class loading. A search that fails is logged to the browser console and reported to the reader as an error notification.

Selection

A picker reports what the reader picks through two events fired on its root element, documented with an example on the attachmentGalleryPicker macro page.

Messages

The four messages of the picker are loaded through xwiki-l10n!, under the prefix attachment.picker., and none of them is defined in this WebJar:

The texts of the two blocks the JavaScript only shows and hides, attachment.picker.macro.notResult.message and attachment.picker.macro.globalSelection.message, belong to the macro module as well.

FAQ

Which of the four blocks may I leave out?

Any of them. Each one is looked up inside the root element, and a block that is not there is quietly skipped instead of raising an error, which costs the picker the feature that block carries: no search field, or a reader who is never told that a search found nothing or that the attachment they picked belongs to another Page.

Related

• Attachment Search Module.
• "attachmentGalleryPicker" Macro.
• Attachment Picker Application.