"gallery" Macro

Last modified by Eleni Cojocariu on 2026/11/16 18:48

Reference

Description

The gallery macro collects the images found in its content and shows them in a slide-show.

Its content can be anything written in the current syntax. Any markup or macro that renders an HTML <img> element contributes its images, which is what makes the feed and page examples below work.

The macro itself only wraps its content in a DIV carrying the gallery class. The gallery.js script then collects the <img> elements from the rendered output and builds the slide-show. A gallery of wiki pages is therefore not possible, because there is nothing to collect but images.

XWiki 18.0.0+ The alternative text of an image carries over to the gallery, unless it is the file name, which the image syntax uses by default.

XWiki 18.9.0+ The gallery takes its background, text and border colors from the panel colors of the current color theme. Its maximize and minimize buttons take their icons from the current icon theme.

The gallery disables the lightbox, so clicking an image does not open it.

Information

The Attachment Gallery Macro shows all the images attached to a page without writing the loop yourself.

Usage

{{gallery}}
image:history-office.jpg
image:[email protected]
image:https://www.example.com/photos/skyline.png
[[image:Welcome.About our Company@team photo.jpg]]
{{/gallery}}

Use the bracketed form when the page name or the file name contains a space.

The macro picker lists the macro under the Layout category. Its dialog offers the three parameters below.

The macro dialog of the editor, with the content field above the class, height and width parameters

The gallery accepts these keys once it has the focus:

KeyAction
←Show the previous image
→Show the next image
HomeShow the first image
EndShow the last image
FMaximize the gallery, or minimize it again
EscMinimize a maximized gallery

A gallery maximized over the whole window, with its navigation arrows and its image counter

Parameters

NameMandatoryAllowed ValuesDefault ValueDescription
classnoCSS class namesnoneExtra CSS classes for the gallery container, to style one gallery.
heightnoa CSS length349pxThe height of the gallery. An empty value sets no explicit height.
widthnoa CSS length620pxThe width of the gallery. An empty value sets no explicit width.

Examples

Show the Images Attached to the Current Page

{{velocity}}
#set ($attachments = $doc.attachmentList)
#if ($attachments.size() > 0)
{{gallery}}
#foreach ($attachment in $attachments)
  #if ($attachment.isImage())
[[image:$attachment.filename]]
  #end
#end
{{/gallery}}
#end
{{/velocity}}

A gallery showing the first of the four images attached to the page, with its counter and its navigation arrows

Show the Images of an RSS Feed

{{gallery}}
{{rss feed="https://api.flickr.com/services/feeds/photos_public.gne?id=44494372@N05&format=rss_200" content="true" decoration="false"/}}
{{/gallery}}

Show the Images of Another Page

{{gallery}}
{{display reference="Sandbox.WebHome"/}}
{{/gallery}}

Lay the Gallery Out on the Bootstrap Grid

{{gallery class="col-xs-12 col-sm-6 col-md-4 col-lg-3" width="" height="300px"}}
image:[email protected]
{{/gallery}}

Related

Get Connected