This design page presents the requirements and designs decision for the new New CKEditor Image Dialog.

This includes:

  • image styling
  • improved image picker
  • captions


Additional interesting to consider:

  • Provide a field to set the image id from the the dialog
  • Allow to change the name of an attachment on upload
  • Allow to drag and drop an file in the upload tab
  • Default styles and tool tips to help the wiki keep a consistent look and feel. (i.e., the same as the macro "wizard").
  • The following parameters should be editable in the UI if the style "Type" allows a custom setting:
    • Caption
    • Alt text
    • Image Style
    • Alignment
    • Wrap Tex
    • Border
    • Image Size (Width / Height)

Image search improvements in Image UI:

  • Add thumbnail to dropdown list + reuse new attachment picker
  • Add image browser with grid layout
  • Move to SOLR-search based search instead of DB-search based for the attachment pick for searching through attachment metadata (including OCR-extracted ones)
  • Ability to search in image caption when specified
  • Don't know how to do it ATM since attachments are indexed when added and captions are defined where the image is used.
  • Put images from the current page first
  • (optional) Search using the OCR data, see above
  • Already supported by our existing SOLR index

Image Improvements: Configuration Options (Superuser UI)

  • Styles should be selectable from a drop down list that is configurable by administrators in terms of available style configurations and a default setting. E.g. Thumbnail images should be of a set size as configured by an administrator and have a frame. We will configure this as the default behavior when an image is added. A user should not be able to override defined styles unless this is explicitly allowed, see below.
  • A configurable option (ON or OFF) to allow users to override aspects of a predefined style. It’s unclear if we want users to have that much freedom. The wiki might look strange if some images have a frame and others don't for example. We appreciate some of the above requirements are specific to our needs so as long as they are configurable that is sufficient.

Image Improvements: Image picker UI

When inserting (or changing an image) we should provide a search box that displays thumbnails of matching images across the wiki(s). Images from the current page should be considered more relevant. Search should also match against caption text and OCR metadata (but with less relevancy).


State of the CKEditor Image Dialog


1645541088254-834.png 1645538341499-156.png

Known limitations

  • Picking an image is difficult
    • no preview of the images
    • limited search
  • No possibility to choose the name of an attachment, or to choose its location


Components dependencies

Image Gallery

See Grid Image Picker.

Image Indexing module


Image search module

  • The attachment search UI will be required:
    • a search images API that allowing to:
      • search on
        • captions (actually a generic description that could be used as a default caption could be interesting)
        • filename
        • OCR
      • filter by rights? - should use the rights of the Page to search (i.e., only show attachments that can be viewed by the users that can view the page?), not the one of the editor/owner
      • ordering to put images from the current document on top (and other criteria)

Style Administration UI

Entry point: 

  • Live Data listing the existing styles + remove and edit actions (according to the user's rights°.
  • dropdown selection of the default style

Style edition form:

  • Text: Free text allowing to input the css class that is attached to the images of the corresponding style. Note that the skins resources must use the same css class in their definitions. Note: Some flexibility could be possible by allowing several css classes to be defined (and in this case some skins CSS could impact several styles, allowing less code duplication)
  • Adaptable position (checkbox)
  • Position (none/start/center/end)
  • Adaptable Text Wrap (checkbox)
  • Text Wrap (checkbox)
  • Adaptable Border (checkbox)
  • Border (checkbox)
  • Adaptable Image Size (checkbox)
  • Image Size Setting:
    • Width (integer)
    • Height (integer)

Description of the modal UI

First tab: image selection


Single text field. The images are displayed in a grid (lazily loaded?) of images corresponding to the search input

When the text field is empty, the attachments from the current page are presented (ordered by the most recently edited?)

Clicking on an image highlights it. Pressing the next button at the bottom right pass to the Image configuration step.

Note: Search on multiple wiki.


Document Tree

The same user experience as the current image plugin, allowing to either type an attachment name, or to browser the tree to select an attachment when the location is already known by the user.



Single file upload field (must allow drag and drop of an image from the filesystem - Existing file upload library, with image preview?)
The attachment name is auto-completed with the selected document name when the field is empty.

Second tab: image configuration

Basic configuration
  • Choice of the image style (see Style administration)
  • Alternative Text
  • Width/Text/aligned are moved to the advanced configuration since impacted by the style choice
  • Caption: Yes/No
Style configuration
  • Position*
  • Wrap Text Yes/No*
  • Border Yes/No*
  • Image Size (integer values in pixels)*
    • Width 
    • Height

*: If allowed by the style

Description of the serialization format

[[Caption>>image:XWikiLogo.png||alt="AAAAA" data-xwiki-image-style='style-type' data-xwiki-image-style-border='true' data-xwiki-image-style-alignment='start|center|end' data-xwiki-image-style-text-wrap='true']]
  • data-xwiki-image-style is optional when not style is selected
  • data-xwiki-image-style-border is optional when its value is false
  • data-xwiki-image-style-alignment is optional when no specific alignment is required
  • data-xwiki-image-style-text-wrap is optional when no text wrap is required



Get Connected