Composr Tutorial: Providing galleries

Written by Chris Graham (ocProducts)

An image in a gallery

An image in a gallery

(Click to enlarge)


Adding an image to a gallery

Adding an image to a gallery

(Click to enlarge)

A gallery system is provided for the storage, organization and viewing of images and videos. The gallery serves much like a gallery in reality: as a direct presentation medium. This tutorial describes the basic gallery features, and how to use them.

Gallery structure and settings


Galleries are structured. Here is a gallery that has a subgallery

Galleries are structured. Here is a gallery that has a subgallery

(Click to enlarge)

A gallery is a category of the gallery system, and is used to hold images and videos (together, gallery entries). Galleries can also hold audio files which are treated in the same way as videos.

Galleries are organised in a hierarchical (tree) structure. For more information of these tree structures, see the Providing downloads tutorial, as the download system is the perfect clean example of a Composr tree-structured system. The gallery structure is more complex than that of the download structure, and additional information on it is given in the Advanced galleries tutorial.

Galleries are given a name, and a title. The name should be a code-name that can easily be typed in a URL, rather than a cleanly readable name. For example, 'holiday2004' would be a good gallery name for a gallery with title, 'Holiday Pictures, 2004 (Sweden)'.

Galleries may have 'representative images' (rep-images). When a user views a gallery with sub-galleries, the sub-galleries are actually shown with their rep-images, so as to make them look more attractive and give an impression of the contents. Rep-images may be chosen when adding or editing a gallery, or when adding an image to a gallery it can be chosen that that image shall also become the rep-image.

You will find icons to add/edit galleries/images/videos at:
Content Management > Galleries

You can delete a gallery/image/video from the bottom of its edit form. The root gallery cannot be deleted, however.

Viewing galleries


A gallery in regular-mode mode

A gallery in regular-mode mode

(Click to enlarge)


A gallery in flow mode

A gallery in flow mode

(Click to enlarge)

There are two display modes for galleries:
  1. Flow mode – this mode allows you to see all the entries in the gallery at the same time as viewing one of the entries. This makes navigation more efficient. Note that there is a limit of 40 media files displayed in the carousel, so flow mode is only a good option for small galleries.
  2. Regular-mode – this mode provides page browsing features so as to be able to browse through a large numbers of entries.

Regardless of display mode, the user can choose any of the available entries (images or videos), and the chosen entry will be presented to the user.

Galleries are viewed from the galleries module (site:galleries page-link, Content > Galleries home on the default menus).

More about gallery display modes

You can lock-down the gallery display mode choice for new galleries using the "Gallery display mode" config option. Existing galleries will only allow the display mode to be changed if it is not already matching the value of this option (i.e. you keep your pre-existing gallery settings, but if you then change a gallery to be the same as the locked-down value then it will then also lock-down).
If the choice is not locked-down then the default will be whatever is the current most common display mode used on your site.


There is a block, main_gallery_embed, that can be used for embedding images and videos directly into another page. The selection of images and videos is based on configurable criteria.

The default look of this block is plain, but advanced slider interfaces can be created by re-templating this block.


Image formats

The following image formats can be used:
  • .jpg/.jpeg – highly compressed, but loses image accuracy. Great for photos because the accuracy loss is hard to notice for natural scenes.
  • .png – well compressed, with no accuracy loss. My personal favourite choice if bandwidth is not generally constrained. Soon will be able to do animation too via APNG.
  • .gif – useful if you need animation, but limited to 256 colours and poor compression. Generally a poor choice, use video or APNG instead.


Galleries have powerful video support. Composr will analyse the file types of uploaded videos and use carefully crafted templates that use browser plug-ins that are most appropriate to that file type. For example, QuickTime files will be displayed with HTML to use the QuickTime plugin.

Composr can usually auto-detect video widths, heights and lengths, from the actual video files.

Video formats

Composr supports most video formats, but video on the web is fraught with complexity.

The following formats are best to use:
  • .mp4 (with h.264 aac encoding)
  • .webm (the Google-sponsored format, supported natively in all web browsers except Internet Explorer/Microsoft Edge and Safari, but available in those via normal system codec plugins)

The following are almost as good:
  • .mov (with h.264 aac encoding – this modern QuickTime format is identical to mp4)
  • .flv (works as long as Flash is installed – won't work on iOS devices)

The following common formats are not safe:
  • .avi (could be many different codecs, no consistent support even for the MPEG-compatible encodings like DivX or XVid or MS-Video, plus your browser might not load the correct plugin)
  • .wmv/.asf (requires Windows Media Player plugin, only properly supported on Windows)
  • .ogv (Ogg video, essentially replaced by WebM)
  • .mpeg/.mpg (old MPEG formats, no consistent plugin support, plus your browser might not load the correct plugin)
  • .rm/.ram (requires RealPlayer plugin, not available on Linux)
  • .qt (Old quicktime format)

Further documentation is provided in the Supplementary web technologies (media, social networking, etc) tutorial.

At the end of the day it may be best just to use the galleries on your site as a wrapper around YouTube. Read on.


You can set it up so that any video format is 'transcoded' to MP4 by setting the FFMPEG executable path in the configuration. For this to work, 'FFMPEG' needs to be installed on the server. The default transcoder settings are set to produce MP4 h.264 DVD-quality movie files.

Unfortunately FFMPEG does have some major problems with audio/video synchronisation, mixed bit-rates, and lack of adaption to corrupt files, and incompatibilities between versions. It is also fairly slow to run, so can consume server resources, and could result in timeouts on some configurations.

The best solutions (for those who can't invest heavily in heavy-weight transcoding solutions) are:
  1. just use YouTube. You can post videos on YouTube, then add a video in Composr using the normal YouTube URL as the video URL. Composr will then automatically embed the YouTube player.
  2. just post in h.264 .mp4 to start with. It has become the standard and is supported in all browsers. The only down-side is having to learn how to set your codec settings right when you make the video file.


Audio is supported as specialisation of video support. i.e. a gallery must have video files enabled for it, for audio files to be supported.

In fact, virtually any kind of media, including random things like URLs to Google Maps, may be posted as a video. The media rendering system Composr uses is quite extensive.

Length, width, and height

Composr can sometimes automatically detect width/height/length of uploaded videos/audio.

If it can't be auto-detected then you should enter it manually, as it can cause various issues, such as misreported lengths in podcasts.

However, if you install the non-bundled getid3 addon then this can work much more consistently.


Gallery entries are ordered in the same order they were added to the system. If you are batch importing (covered in the Advanced galleries tutorial), then you may want to define a custom ordering. To do this, you just need to give all the images in the batch names that are consistent with a numbering scheme of your choice. Composr will detect numbering schemes automatically, and order by them.

The rule is very simple: Composr will order by filename if when taking all numbers out of all filenames in the gallery, the filenames are all the same.

For example, a gallery with the following named files would not be ordered according to a scheme:
  • foo.png
  • foo1.png
  • foo2.png
  • foo2something.png
But without the last image, the contents would be ordered by filename.


When viewing an image or video visitors will be able to start moving through all the subsequent images/videos in the gallery automatically. This is referred to as a slide-show. Visitors may pause the slide-show via a click or keypress, which could be triggered via a hand-held USB control device (as such devices can be mapped to such input actions).
If you would like to change the speed of the slide-show you can do it via editing the GALLERY_ENTRY_SCREEN.tpl template.

On some browsers, alt-clicking on the slideshow will activate the browser full screen mode.


When you add or edit a gallery you may choose watermarks to be automatically added to any of the 4 corners of any added images that you select to be watermarked. A watermark is just a semi-transparent image that is overlaid across images as an official mark, or to prevent unauthorised reproduction. If you wish to place a watermark on an edge, you simply make a corner watermark image that includes enough transparency to change the location for the main image to be placed.

Watermarks will appear on your full image where-ever it is displayed. Composr will not save a copy of images without the watermarks applied. They are applied permanently when you add/edit new image files. You will therefore want to ensure you keep your own media archive should you wish to change how you do watermarking later on.

Watermarks are actually 'inherited' in the tree structure: in other words, when adding an image, watermarks will be chosen from the first gallery back down towards the root gallery that actually defines watermarks.


When viewing an image visitors will have an option (if the recommend addon is installed) to send the image as an e-card. This is a good form of website promotion, as the e-card also functions as a kind of website recommendation.
If you don't want this feature you can remove it by editing the GALLERY_ENTRY_SCREEN.tpl template.


A category for images and videos
An image chosen to represent a category, when a box for it is displayed
A standard mark shown on an image to mark its identity, often done for a number of different reasons
Flow mode
The gallery view mode intended for attractive display of small galleries
A gallery placed beneath another gallery

See also


Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.