Create a Custom Image Set - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 10. There's an updated version available that covers our most recent release.


Create a Custom Image Set

Hippo CMS stores several variants of each uploaded image. All variants of an image are together called an image set, and can be seen in the image gallery in the CMS. The default image set contains only two image variants: the original image, and a small thumbnail that is used in the CMS in listings and pickers.

The default image set type is hippogallery:imageset. Besides the original and thumbnail variants, this type also stores size information (width and height) for each image in the set. In addition, the original file name is stored.

The default image set can be extended with more scaled variants of each uploaded image. It is even possible to create multiple, different extensions of the default image set that each contain a different set of scaled variants. Having multiple custom image sets can be useful if not all uploaded images need to generate all scaled variants, e.g. when parts of the image gallery are only used by specific channels that only render certain image variants.

Hippo's setup application provides a Gallery Manager tool which lets you configure custom image sets through a UI.

Do Not Change Thumbnail Dimensions

The standard 'thumbnail' variant is used by the CMS, changing its dimensions or other configuration properties can cause issues. A custom thumbnail variant should be created for use on the site.

The following example creates a custom image set that contains an additional 'preview' variant of the image of at most 640x480 pixels.

1. Subtype the base type

Add a custom image set type to your project's .cnd file. Example:


[myproject:myimageset] > hippogallery:imageset, hippogallery:relaxed

There are two options to get this changed CND into your local development repository:

  • Rebuild and restart your project with a clean repository
  • Select 'CND Import' in the top of the console and import your .cnd file

Verify with 'CND export' that the type myproject:myimageset is now used by the repository.

To make sure the .cnd file is also re-imported in existing repositories (e.g. on your production server), add a reloadonstartup property to the initialize item for the .cnd file in the hippoecm-extension.xml file.

2. Create a document type for the new imageset

The new imageset needs a custom document type. Unfortunately, the document type editor cannot be used here since it does not support inheritance from types in different namespaces. The easiest way to create the document type is therefore to copy the hippogallery:imageset document type definition in the console, and add/change the right properties and nodes in there. As an example, we're going to create an imageset called myimageset with an additional image variant called preview.

  1. In the console, copy the node



  2. Change the supertype of the copied imageset. In the node


    set the multiple property hipposysedit:supertype to the values hippogallery:imageset and hippogallery:relaxed. Also set the property  hipposysedit:uri to the URI of your project's namespace (see the .cnd file).

  3. Add a nodetype definition to the myimageset document type. In the node
    copy the node original to preview and change its property hipposysedit:path to myproject:preview.
  4. Add a template definition to the myimageset document type. In the node
    copy the node original to preview and change its property field to  preview. Also change the property caption to Preview.
  5. Change the primary type of the prototype node of the new image set: select the node
    and change its primary type to myproject:myimageset.


  6. Next, we have to add the new variant to the prototype of the new imageset. In the node
    copy the node hippogallery:original to myproject:preview.
  7. Finally, we have to provide translations for the new 'preview' variant. Copy all the nodes
    where the hippo:property equals hippogallery:original to new hippo:translation nodes (five nodes in the default hippo archetype: one translation for de, en, fr, it and nl).
  8. In the copied nodes: change hippo:property from hippogallery:original to myproject:preview, and enter the translations in hippo:message (for example 'Preview' for English, 'Voorvertoning' for Dutch, etc.)

  9. Save your changes

Note that this only provides translated labels that are used in the gallery picker. To translate the labels an editor sees when editing an imageset, use the mechanism to add internationalization to document types. Export this new nodetype back to your project using manual XML export or the automatic export feature.

3. Configure the queries used to create a new image in the gallery

In the console, go to the node

/hippo:configuration/hippo:queries/hippo:templates/new-image-folder/hippostd:templates/image gallery

Change the property hippostd:gallerytype to myproject:myimageset. Also change this property in all existing folder nodes below /content/gallery to ensure that the new imageset will also be used in existing gallery folders.

To adapt this query while bootstrapping the repository, import the following delta XML at the right node (e.g. /hippo:configuration/hippo:queries/hippo:templates/new-image-folder/hippostd:templates):

<sv:node xmlns:sv=""
         sv:name="image gallery" h:merge="combine">
  <sv:property sv:name="hippostd:gallerytype" sv:type="String"

4. Configure the gallery processor

All image variants in an image set are created by the gallery processor. When adding a new image variant, the gallery processor should be told what size to scale the original image to.

The following image types are supported: JPEG, GIF, PNG, BMP and SVG files (using pixels units).

The configuration of the gallery processor resides under the node


Each image variant is configured as a child node with the same name as the property in the CND (in our example: myproject:preview). Two nodes already exist: hippogallery:original and hippogallery:thumbnail, for the original and thumbnail variant. Each child node contains the following properties:

  • width and height

    The size of a bounding box in pixels. The original image is scaled such that it fits in this bounding box while maintaining the original aspect ratio. A width or height of 0 or less means "unbounded", and results in a bounding box that does not restrict scaling in either the width or height, respectively. When both width and height are 0 or less, the image is not scaled at all but merely copied. The default width and height is 0.

    Setting width & height to zero is not supported by the cropping functionality, since it breaks the UI display of the image variant.
  • upscaling

    Whether to scale images up that are smaller than the specified bounding box. Its value can be true or false. The default value is false.

  • optimize

    The scaling optimization strategy. Possible values are:

    • speed 

    • speed.and.quality

    • quality

    • best.quality

    • auto

    The default is quality. These settings relate to methods SPEED, BALANCED, QUALITY, ULTRA_QUALITY and AUTOMATIC from Scalr.Method.

  • compression

    The compression quality to use when writing the scaled image data, specified as a double between 0 and 1. The lower the value, the higher the compression. The default compression quality is 1, meaning 'no compression'. Note that only JPEG images can actually be compressed. Other image formats (like GIF) will simply ignore the compression quality.

Changes to the gallery processor configuration are picked up when the CMS is re-rendered, i.e. after refreshing the page in the browser, or after logging out and in again.


The following image gives an idea of how setting the width and height works with 2 example bounding boxes (red and blue) and 2 example original images. Note that Hippo CMS doesn't add white space in thumbnails, so the generated thumbnails will usually be in various sizes:

For the example 'preview' image version, copy the child node hippogallery:thumbnail to myproject:preview and set the following properties:

- width = 640
- height = 480

5. Use the custom image set in your HST site

To use the custom image set in your HST site, create a Java bean for it. For example:

@Node(jcrType = "myproject:myimageset")
public class MyImageSet extends HippoGalleryImageSet {

    public HippoResourceBean getPreview() {
        return getBean("myproject:preview");
Make sure that the HST can find your new image set bean. Either add the image set bean to the same package as your document beans, or add the new Java package to your HST bean scanning configuration.

A document bean can then return the custom image set bean in a getter method. For example, a document with a field 'logo' could have a 'getLogo' method that returns the custom image set:

public MyImageSet getLogo() {
    return getLinkedBean("myproject:logo", MyImageSetBean.class);

6. Tweak the URLs of image variants

By default, the URLs for the 'preview' variant of a 'logo.jpg' image would be something like /binaries/content/gallery/mysite/logo.jpg/logo.jpg/myimageset:preview. With some additional configuration this URL can be changed to, for example, /binaries/preview/content/gallery/mysite/logo.jpg. Such URLs can be created by the HST by configuring custom resource containers.


Related notes

Some things to be aware of while working with images:

Cropping images from within imageset editor

The built-in image cropper provides for each variant the ability to select a portion of the original image and crop around that. The dimensions ratio used for the cropping operation is fixed and calculated from the variant's dimensions. With respect to the upscaling property specified for each variant, the cropper may not allow crop selections smaller than the thumbnail variant size, effectively preventing upscaling of the cropped region. This is an extension to the normal cropper behavior, which out of the box supports all features of the YUI Image Cropper. Documentation about this can be found at the YUI website.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?