Image styles and figures

Hello all,

We currently have a limitation regarding the image style when the image is wrapped in a figure element.
The image style is attached to the image, and not to the figure. Hence, it’s not possible to define a CSS selector to keep the figures style consistent.

Know use cases are:

  • Define a given width for the captions
  • Add a border to the figure containing the image (e.g., to have a frame around the image and its caption)

Currently in XS, there is two way to produce a figure tag:

  • Using the image figure with caption [[Caption>>Doc@image.png]]
  • Using the figure macro and placing an image inside

Functional proposal
Search for the first image contained in the figure.
If it exists, move the data-xwiki-image-style* attributes from that image to the figure (if other images exists, the first one takes priority)

Technical proposal

  • Need to be applied on the XDOM as the image figure with caption and the figure macro are not working in the same way (let alone other ways from other extensions)
  • Need to be defined in the xwiki-platform-image-style module

Given those constraints, I propose to implement this as a Transformation.


  • easy to implement and test


  • The rendering.transformations key from needs to be maintained:
    • By adding the new transformation on upgrade
    • By removing it if the image style extension is uninstalled

Other solutions I considered required:

  • anticipation (i.e., ad-hoc generic code in the transformation modules to allow the image style extension to define it own behavior)
  • duplication since the code of the image figure caption and the figure macro has nothing in common until the transformation steps


Another reason is that this makes it independent of the syntax used (since if you don’t do it at the XDOM level then you have to do it at the syntax parsing level and then it needs to be implemented for all syntaxes that need to support this feature).

We could imagine implementing a mechanism similar to xwiki-platform/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-transformations/xwiki-platform-rendering-transformation-api/src/main/java/org/xwiki/rendering/internal/transformation/ at 15c0d2d391c11ba8f4d470908d485d9559523fe6 · xwiki/xwiki-platform · GitHub to allow extensions/components to automatically add a transformation, without having to configure it in

Re the cons, it’s possible that the non-inplace-wysiwyg editor doesn’t execute all transformations, this would need to be checked.

It also decreases slightly the performance of page views since it means traversing the full XDOM. The longer the page is the slower it’ll take.

Ideally the best solution would be to let the user define the style to be used on the figure.

For the figure macro this could be achieved using some parameters.

For the syntax, this could be achieved in endParagraph() in DefaultXWikiGeneratorListener (where the image syntax is converted to a figure macro if standalone), by copying the style to the figure macro using the new parameter defined above.

Note that this means it would work for all wikimodel-based syntaxes (which is the situation right now for the image caption syntax support anyway).

That’s not correct: endParagraph() generates a FigureBlock, not a figure macro.

So one idea would be to copy all parameters from the image caption syntax to the figure event in endParagraph() (in DefaultXWikiGeneratorListener). The logic being that the code converts an image to a figure so it kind of make sense to copy the parameters on the figure. One exception could be done if there’s an id parameter since that’s meant to be unique.