Description

Picking an attachment is currently made difficult by several UI limitations:

• only small thumbnails of attachments are presented to the user
• it is not easily possible to see attachments preview in full size (in particular for images)
• there is not notion of priority between attachments (for instance, attachments from the current document cannot be identified)

Table of Content

• Table of Content
• Requirements
• Architecture
  • Macro parameters
• UI
  • Search algorithm
  • User input
  • Image box size
  • Max items
  • Preload
  • Search Scope
• Analysis

Requirements

• R1: attachment can be searched using a single text field
• R2: Results are presented in the form of same-height thumbnails
• R3: Results are retrieved from solr WarningTODO: define how results are sorted.
• R4: Attachments from the current page are displayed when no search value set
• R5: Attachments from the current page are displayed first
• R6: (optional) possibility to see an attachments in full length (and to move between attachments in a lightbox gallery)
• R7: a single attachment can be selected from the picker

Architecture

• Name of the macro: attachmentPicker
• Module: xwiki-platform-attachment-picker.
  • xwiki-platform-attachment-picker-macro: contains the code of the Java macro
  • xwiki-platform-attachment-picker-war: contains a single javascript file with some velocity to resolve the dependencies, and call the main file of xwiki-platform-attachment-picker-webjar
  • xwiki-platform-attachment-picker-webjar: contains the main javascript and css code of the extension

The part related to the popover and lightbox should be made optional and located in a separate module, located in xwiki-platform-image-lightbox-attachment-picker. This module listen for attachment picker events and enrich the UI with the popover and lighbox when it is installed.

Macro parameters

• filter: (List of strings, default empty list) mime type of file extensions
• limit: (integer, default 20) the max number of attachments to display in the search result
• defaultQuery: (string, default empty string) the default query used for the search (only when prefetch is true)
• prefetch: (boolean, default true) when true, defaultQuery is used to perform a search when the macro is displayed. Otherwise the user needs to start typing a search to have a result.
• cssClass: A CSS class for the element surrounding the macro

UI

Attachments are displayed in a grid, with their name displayed below their preview. If the size of the name is too large, it is trimmed but hovering on the preview or text shows the full name.

Clicking on an images selects it.

On hover, a popover is displayed. The popover propose an action to preview the image in a lightbox.

Search algorithm

• N = 20
• search criteria = text input from the user. In case of empty string, '*' (joker) is used instead.
• attachmentsLocal = N attachments retrieved from the current document using the search criteria.
• attachmentsGlobal = N attachments are retrieved from the whole farm using the search criteria
• filteredAttachmentsGlobal = attachmentsGlobal where only the attachments with an id not found in attachmentsLocal are kept
• attachmentsFile = attachmentsLocal + filteredAttachmentsGlobal truncated the size N.

The results are retrieved by calling XWiki.SuggestSolrService.

User input

The user can input a text . The field input events are debounced at 200ms. This means that if the user types a sequence of characters, an event will be fired only when they stop typing.

Image box size

Currently can be changed using CSS only. Note that changing the CSS won't change the size of the attachments preview sizes requested from the attachments src attribute, so setting a larger css witdh/height will force images to scale up (possible degraded preview quality).

Max items

Currently the max number of items is 20 (not configurable).

Preload

Only when prefetch is true.

Search Scope

Analysis

Based on blueimp gallery and the Image Lightbox Application.

Design choices and questions:

• we need to both allow to click on an image to select it (highlighted with a colored border or a checkbox?) and to preview the image in full width in a lightbox (reusing the popover from lightbox?)