Image/attachment Grid picker macro

[mleduc]

Hello all,
In the context of the new CKEditor Image plugin, I’d like to add a new image selection tab, where the user can type keywords and obtain a grid of images as a results.

While the attachment picker widget already exists, it is mainly relevant when vertical space is limited. But, the pre-visualization is not really great with very small attachments preview.

While the primary use case is the CKEditor image plugin selection search dialog, do we want to generalize the macro to support all sorts of attachments?
The advantage would be to make the macro applicable in more contexts in the future. On the other hand might take more development time, and could make it harder to implement some interesting use case (e.g., opening a lightbox on the image results, allowing to preview images in full size. This which would not work out of the box for non-image attachments).

Also, do we agree to make this feature part of XWiki Standard?

In any case I propose to start with a minimal version where:

• only image search is supported
• only a single element can be selected
• images from all the farm (and viewable by the current user) are returned
• images from the current document are displayed first

And to eventually plan for the following improvements:

• support for more attachment types
• support for multi select
• support for a search scope (wiki/space/page)

You can also consult the corresponding design page Grid Attachment Picker (Proposal.Grid Attachment Picker) - XWiki

I propose to introduce this as a Java macro in:

• If we limit ourselves to images: A new module xwiki-platform-image-picker modules (containing xwiki-image-picker-macro, xwiki-image-picker-api, and any other useful modules)
• If we decide to generalize to attachments: A new modules xwiki-platform-attachment-picker module (containing xwiki-attachment-picker-macro, xwiki-attachment-picker-api, and any other useful modules).

WDYT?

[tmortagne]

@mleduc

While the primary use case is the CKEditor image plugin selection search dialog, do we want to generalize the macro to support all sorts of attachments?

It is definitely tempting.

@mleduc

could make it harder to implement some interesting use case (e.g., opening a lightbox on the image results, allowing to preview images in full size. This which would not work out of the box for non-image attachments)

It’s definitely more work to design a generic API that make sense for all, but I guess one trick is to give each type handler a lot of freedom on what it can expose. But I don’t see any logic problem with the fact that some types of attachments support more visualization features than others (some attachments won’t even be previewed at all because it’s not visual things, or it’s way too expensive in the context of a picker).

@mleduc

Also, do we agree to make this feature part of XWiki Standard?

+1, at least the generic picker and the image type support, but support for other types might come from extensions I guess

[mflorea]

@mleduc

While the primary use case is the CKEditor image plugin selection search dialog, do we want to generalize the macro to support all sorts of attachments?

I think we should because:

• the output is an attachment reference
• and you can always associate a visual (image) representation of an attachment: the icon corresponding to the attachment mime type (or the default icon), even if it’s not unique (we can also have the same image attached with different names so it’s not a problem)

@mleduc

Also, do we agree to make this feature part of XWiki Standard?

+1

@mleduc

If we decide to generalize to attachments: A new modules xwiki-platform-attachment-picker module (containing xwiki-attachment-picker-macro, xwiki-attachment-picker-api, and any other useful modules).

I’d go for the more generic one. Note that there is also an Attachment Selector macro that overlaps with this new attachment picker (if we choose the generic solution) so we may want to cover the features of the old attachment selector in order to be able to deprecate / replace it in the future with the new one.

[mleduc]

Thanks for your answer. So to summarize the macro will support any kind of attachments (in module xwiki-platform-attachment-picker).

I think a filtering by mimetype or file extension, alike the attachment picker is enough.
What propose @tmortagne with modular extensions for different file types is interesting but feels complicated for a first iteration.

Future improvements:

• support for multi select
• support for a search scope (wiki/space/page)
• support for file upload

To go further into the details, I’ll summarize some of the key points I’ve added to the design page

The macro will be named attachmentPicker and will be implemented as a Java macro.
It will support the following parameters:

• types: (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
• 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.
• defaultQuery: (string, default empty string) the default query used for the search (only when prefetch is true)

Regarding the user interactions:

• the input field is debounced at 200ms to prevent solr queries to be fired to often
• the results are fetched from XWiki.SuggestSolrService
• the results are order so that the attachments from the current document are displayed first see the algorithm
• clicking on an image selects is. An event is send to notify external listener of the selection
• a popover is displayed on hover, with an action to open a lightbox (reusing the code from the image lightbox extension)

Here is a preview how what is currently looks like:

Thanks.

PS: I have opened a very unfinished draft PR XWIKI-19651: Introduce the grid attachment picker macro by manuelleduc · Pull Request #1832 · xwiki/xwiki-platform · GitHub

[tmortagne]

@mleduc

types: (string, default empty string) mime type of file extensions

You mean string list ?

Unless you meant a regex to match mime types ?

[mleduc]

@tmortagne

You mean string list ?

I was thinking comma separated list, quoting Suggest Attachments documentation:

The value is a comma separated list of:

• file name extensions (e.g. .png,.pdf)
• complete or partial media types (e.g. image/,video/mpeg)

If nothing is specified then no restriction is applied.

[tmortagne]

My point is that since we are talking about a macro here, you could use List<String> as parameter type.

[mleduc]

@tmortagne

My point is that since we are talking about a macro here, you could use List<String> as parameter type.

Indeed, thanks. Design updated!

[vmassol]

@mleduc

While the primary use case is the CKEditor image plugin selection search dialog, do we want to generalize the macro to support all sorts of attachments?

I agree that this would be good.

@mleduc

Also, do we agree to make this feature part of XWiki Standard?

Yes

@mflorea

Note that there is also an Attachment Selector macro that overlaps with this new attachment picker (if we choose the generic solution) so we may want to cover the features of the old attachment selector in order to be able to deprecate / replace it in the future with the new one.

+1

@mleduc

The macro will be named attachmentPicker and will be implemented as a Java macro.

Or attachmentSelector I guess. Is it to avoid the clash with Attachment Application (XWiki.org) that you chose {{attachmentPicker}}?

@mleduc

It will support the following parameters

What about the features from Attachment Application (XWiki.org) ?

@mleduc

the results are order so that the attachments from the current document are displayed first see the algorithm

That probably needs to be configurable with some macro parameters. It sounds good to have it like you suggest by default though.

@mleduc

a popover is displayed on hover, with an action to open a lightbox (reusing the code from the image lightbox extension)

I think it could be good to make it independent of the lightbox module so that if it’s not installed (or enabled) then the picker will still work. Right now the lightbox module is supposed to be optional.

[mleduc]

@vmassol

Or attachmentSelector I guess. Is it to avoid the clash with Attachment Application (XWiki.org) that you chose {{attachmentPicker}}?

Yes

@vmassol

What about the features from Attachment Application (XWiki.org) ?

I’ll integrate them as much as possible, if I can’t I’ll create improvement jira issue for them (unless some of them are considered as essential for a first version).

@vmassol

That probably needs to be configurable with some macro parameters. It sounds good to have it like you suggest by default though.

I could add a displayCurrentFirst boolean parameter (the name can be changed) to only display global results. This could slightly improve perfs since only a single ajax query would be needed when set to false.
Unless we want some finer mechanism?

@vmassol

I think it could be good to make it independent of the lightbox module so that if it’s not installed (or enabled) then the picker will still work. Right now the lightbox module is supposed to be optional.

Indeed sounds better. I’ll need to check how to handle this kind of optional dependencies client side.

[vmassol]

@mleduc

I’ll integrate them as much as possible, if I can’t I’ll create improvement jira issue for them (unless some of them are considered as essential for a first version).

My point is that the design for the new macro should include it, even if not implemented right away.

@mleduc

I could add a displayCurrentFirst boolean parameter (the name can be changed) to only display global results. This could slightly improve perfs since only a single ajax query would be needed when set to false.
Unless we want some finer mechanism?

A more extensible idea would to provide a sort=<sort component hint>, and the component with this hint will be used to sort the matches. Or something like that.

@mleduc

Indeed sounds better. I’ll need to check how to handle this kind of optional dependencies client side.

One idea would be to use client side events.

[mleduc]

@vmassol

My point is that the design for the new macro should include it, even if not implemented right away.

Definitely, I’ll update the design page.

@vmassol

A more extensible idea would to provide a sort=<sort component hint>, and the component with this hint will be used to sort the matches. Or something like that.

I like the idea. @mflorea do you know of if already have implemented this kind of mechanism for other macros?
Otherwise we could start with a fixed set of client side components hints, and make it extensible in a second step.

@vmassol

One idea would be to use client side events.

Another lead is to use require as a self dependency to check whether an given module is available (see javascript - requireJS optional dependency - Stack Overflow).

[vmassol]

@mleduc

Another lead is to use require as a self dependency to check whether an given module is available (see javascript - requireJS optional dependency - Stack Overflow).

Maybe I’m wrong but if you check for require of lightbox inside the attachment picker then you’re hardcoding it and creating a dependency on it.

[mleduc]

@vmassol

Maybe I’m wrong but if you check for require of lightbox inside the attachment picker then you’re hardcoding it and creating a dependency on it.

An optional dependency, but still a dependency I agree.
Another option is to move the generic parts of lighbox to another module and to depend on it.
That way we don’t depend on lighbox while keeping a consistent look and feel.

[vmassol]

@mleduc

Another option is to move the generic parts of lighbox to another module and to depend on it.
That way we don’t depend on lighbox while keeping a consistent look and feel.

That’s the same to me

Why not do as I mentioned? The picker sends some events and then in a submodule of the lightbox module this event is received and processed. In this manner, everything related to lightbox is located in the lightbox modules.

[mleduc]

@vmassol

Why not do as I mentioned? The picker sends some events and then in a submodule of the lightbox module this event is received and processed. In this manner, everything related to lightbox is located in the lightbox modules.

Ah yes, I had not considered this option. Sounds good. Thanks for the suggestion

[mflorea]

@mleduc

I like the idea. @mflorea do you know of if already have implemented this kind of mechanism for other macros?
Otherwise we could start with a fixed set of client side components hints, and make it extensible in a second step.

The hint is the id of a RequireJS module, or a suffix (in case you want to force a prefix such as xwiki-). The RequireJS module config is published using RequireJS Module Config (XWiki.org) .