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

Create a custom image set 

http://www.onehippo.org/binaries/sixteencolumn/content/gallery/connect/library/multiple_images.png

Hippo CMS stores several versions of each uploaded image. All versions 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 versions: the original image, and a small thumbnail that is used in the CMS in listings and pickers.

Adding new image sizes (in CMS 7.5 and higher)

Hippo CMS 7.5 introduced a new image set type: hippogallery:imageset. Besides the original and thumbnail images, this type also stores size information (width and height) for each image in the set. In addition, the original file name is stored.

The new image set can be easily extended with more scaled versions of each uploaded image. The following example creates a custom image set that contains an additional 'preview' version of the image of at most 640x480 pixels.

1. Subtype the base type

Create a type in your project that defines the additional image versions.

In CMS 7.5, each image version must be of the type hippogallery:image. Make sure you also specify the default type for the node, which must also be of type hippogallery:image. If the default type is not defined then no thumbnail will be generated for this variant. Example:

<'hippogallery'='http://www.onehippo.org/jcr/hippogallery/nt/2.0'>

[myproject:myimageset] > hippogallery:imageset
 + myproject:preview (hippogallery:image) = hippogallery:image

In CMS 7.6 and higher, the imageset can be relaxed and the CND becomes much simpler because it is no longer necessary to explicitly list each variant. Example CND:

<'hippogallery'='http://www.onehippo.org/jcr/hippogallery/nt/2.0'>

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

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 (yet). The easiest way to create the document type is therefore to copy the hippogallery:imageset document type definition 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

    /hippo:namespaces/hippogallery/imageset

    to

    /hippo:namespaces/myproject/myimageset
  2. Change the supertype of the copied imageset: in the node

    /hippo:namespaces/myproject/myimageset/hipposysedit:nodetype/hipposysedit:nodetype

    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.

  3. Add a nodetype definition to the myimageset document type: in the node

    /hippo:namespaces/myproject/myimageset/hipposysedit:nodetype/hipposysedit:nodetype

    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

    /hippo:namespaces/myproject/myimageset/editor:templates/_default_

    copy the node 'original' to 'preview' and change its property 'field' to 'preview'. Also change the property 'caption' to 'Preview'.

Now we have to change the property jcr:primaryType of the prototype node in the new imageset. That cannot be done directly in the console, so we have to export the node to XML, change the type in there, and then import it back:

  1. Export

    /hippo:namespaces/myproject/myimageset/hipposysedit:prototypes/

    to an XML file

  2. In the exported XML file, locate:

    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>hippogallery:imageset</sv:value>
    </sv:property>

    and change it to:

    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>myproject:myimageset</sv:value>
    </sv:property>
  3. Save the .xml file

  4. Import the XML file at

    /hippo:namespaces/myproject/myimageset

    In the import dialog, set 'Merge behavior' to 'Overwrite same name nodes'.

The property jcr:primaryType of the node hipposysedit:prototype should now be 'myproject:myimageset'.

Next, we have to add the new variant to the prototype of the new imageset:

  1. In the node

    /hippo:namespaces/myproject/myimageset/hipposysedit:prototypes/hipposysedit:prototype

    copy the node 'hippogallery:original' to 'myproject:preview'.

Finally, we have to provide translations for the new 'preview' variant:

  1. Copy all the nodes

    /hippo:namespaces/myproject/myimageset/hippo:translation

    where the hippo:property equals hippogallery:original to new hippo:translation nodes (three nodes in the default hippo archetype: one translation for nl, en and fr).

  2. 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, 'Voorbeeld' for Dutch, etc.)

  3. Write changes

Export this new nodetype back to your project using manual XML export or the automatic export feature.

3. Configure the queries used the 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

set the property 'hippostd:gallerytype' to 'myproject:myimageset'. Also change this property in all existing folder nodes under '/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="http://www.jcp.org/jcr/sv/1.0" xmlns:h="http://www.onehippo.org/jcr/xmlimport" sv:name="image gallery" h:merge="combine">
  <sv:property sv:name="hippostd:gallerytype" sv:type="String" h:merge="override">
    <sv:value>myproject:myimageset</sv:value>
  </sv:property>
</sv:node>

4. Configure the gallery processor

All image versions in an image set are created by the gallery processor. When adding a new image version, the gallery processor should be told what size to scale the original image to. This can be done in the node

/hippo:configuration/hippo:frontend/cms/cms-services/galleryProcessorService

Each image version is configured in 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 version. Each child node contains the following properties:

  • width and height specify 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.

  • upscaling specifies 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 [since 2.22.02 (7.7.1) and 2.20.09 (7.6)] for choosing a scaling optimization strategy. Possible values are: 'speed', 'speed.and.quality', 'quality', 'best.quality' or 'auto'. The default is 'quality'. These settings relate to methods SPEED, BALANCED, QUALITY, ULTRA_QUALITY and AUTOMATIC from Scalr.Method, see http://www.thebuzzmedia.com/downloads/software/imgscalr/javadoc/org/imgscalr/Scalr.Method.html.

  • compression [since 2.22.08 (7.7.5) and 2.23.05 (7.8)] specifies a double between 0 and 1 that indicates the compression quality to use when writing the scaled image data. 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.

Example:

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:

 

http://www.onehippo.org/binaries/sixteencolumn/content/gallery/connect/library/thumbnails-generation.jpg

For the example 'preview' image version, copy the child node 'hippogallery:thumbnail' to 'myproject:preview' and set the following properties: width = 640, height = 480.

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.

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

5. Configure your HST site

To use the new imageset variant in your site, you have to create your own bean for the imageset and configure the resource servlet. All this is explained in the wiki page Custom Resource Containers.

Related notes

Uploading images from within Hippo CMS

Hippo CMS comes with two flavors of uploading images: one is based on Flash and can simultaneously upload multiple images, the other one works without any browser plugin and is based on Wicket but can only upload a single image at a time. This is not to be confused with the ability to select multiple images for upload; both uploaders support that. The difference is in the actual uploading, whether it happens concurrently for all selected images or one by one. The Flash based implementation has of course the disadvantage that the browser must have this plugin installed. There is also a subtle other limitation: it does not work behind a proxy and does not work with self-signed certificates on a HTTPS server. See http://developer.yahoo.com/yui/uploader/ for more information. Go here for instructions on how to disable Flash for this function within Hippo CMS.

Cropping images from within imageset editor

From Hippo CMS 7.5 and onwards, cropping of images is supported for all imageset variants, custom and built in. The 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 on this can be found at the YUI website.