Dynamic image processing with Enonic CMS

16/07/2010 18:38

For a decade, Enonic CMS has provided smooth handling of images for both content creators and developers. By pre-scaling multiple sizes of an image and letting the content creators relate to the image (outside of the editor) - the developers have easily been able to choose the proper size and placement for various presentations and sites. As of release 4.4 (2009) Enonic CMS sets a new industry standard for image handling - say hello to relative image sizes and the image processing filter.

Introducing the Enonic Content model

Enonic CMS - as oppose to many other WCM's - treats images and other "assets" in the same way as an article - they are all "content objects". The model is quite similar to an e-mail actually (data + attachments), however as oppose to an e-mail the data part is structured, and can even mix both structured and unstructured (xhtml) content.

Image objects

Images in Enonic CMS are stored with a data-part, containing information such as name, photographer, copyright, description etc. The "image file" itself is stored as an attachment to this "image object". However, when saving - depending on the size of the image - up to three additional attachments are also stored for performance reasons. These three attacments are labelled "small" (256px), "medum" (512px) and "large" (1024px). The original image is labelled "source". When generating new images (described below), developers may choose to use a smaller image than the original image to speed up the initial image generation.

Native links and relative image sizes in the HTML area

Enonic CMS 4.4 changes the game in relation to image references, and event other links from within the HTML editor.

Native links

Enonic CMS provides market-leading multi-channel support. To achieve this, content is stored out of context - making it reusable across different sites, devices and formats. As a consequence, every URL's must be generated for each site and context where the document is actually presented. As such Enonic CMS needs to persist links in a format which safely can be used for this purpose - native links to the resque.  Native links are now stored inside the xhtml when the content is saved. The link format, typically placed within <a href=""> or <img src=""> elements has the following format:

scheme://key?param1=value1&param2=value2..

There are four types of schemes:

• page
• attachment
• content
• image

Common to all schemes is that they at any time later can be deschiffered and used to create real url's with portal functions such as createPageUrl(), createAttachmentUrl() etc.

Note: As of CMS 4.4. links inside HTML areas also store relationships to other content objects - making the relationship visible from the "in use by" pane on the target content objects, as well as the capability to query these relations.

Native image links

Since this article focuses on images we will in particular dive into native image links - in fact, this is also the most complex of them.

The very simplest version of a native image link would look like this:

image://<contentkey>

As you can see, it simply contains the key to the image content object. However, a more complexversion might look like this:

image://<contentkey>?_size=custom&_filter=scalewidth(300)

Please notice the _size parameter, this actually refers to what is known as the relative size of the image. We will get back to the other parameters later.

Relative images sizes

In order to adopt images automatically to different contextual presentations (for instance mobile or pc) Enonic CMS has introduced what is known as relative image sizes. Relative image sizes are simply a set of names. The html editor presents a default view of these when editing content - but this might look different for each presentation since it is actually the developers whom control the final result.

Below you can see all relative sizes, and how they are actually rendered in this context. Try out the mobile version of this site (if available) to see a different presentation as well:

Above: Thumbnail (as rendered by templates on this site)

Above: List (as rendered by templates on this site)

Above: Square (as rendered by templates on this site)

Above: Regular (as rendered by templates on this site)

Above: Wide size (as rendered by templates on this site)

Above: Full (as rendered on this site)

Additional sizes are Original and Custom. These sizes will respectively give you exact sizes, but editors should only uses these sizes for special purposes, i.e. when displaying an icon, original size might come in handy.

createImageUrl() and the image service

It is clear that to actually enable relative image sizes, Enonic CMS must have the capability to generate images on the fly. For this purpose we have built the image service

The image service

The image service is not only capable of scaling images, but has a wide range of filters whom may be applied on demand by the developers. Effects such as rounded corners, borders, hsb filters, and a whole lot more have been implemented. In addition to effects it can create output amont the most commonly used image formats (including jpg, bmp and more), where png is the default format - primarily due to the alpha channel support.

Given the reference to an attachment (of an image file naturally) the image service of processing the input image, and responding with the desired result!

Please note that when using the image service from ICE mode it will be readable in clear-text, whilst it is currently encoded in production mode, simply to limit the possibilities for abuse of the service.

Image caching

To maximize performance, the image service provides both server-side and client-side cache. An image is only rendered once per node (in a cluster), and is then cached in memory on the server. In regards to client cache, the image servlet implements a "perfect cache" solution, where the HTTP headers instruct both proxies and browsers to retain the image in their cache forever - but not without setting the proper private/public headers to maintain network security. If the source image on the server should change, or a different filter be applied - this will always result in a new URL and a new unique image.

The image service is an integrated part of the Enonic CMS portal. Given the proper URL invocation and parameters it will output images tuned to  your heart desires. :)

createImageUrl()

In order to build URL's referencing the image service, a new portal function has been created: createImageUrl().

This portal function can be invoked with from 2 to 5 parameters:

createImageUrl(attachmentkey, filter, background-color, format, quality).

Some of the parameters are pretty self-explanatory, but we will take a deeper look into the filter parameter, since this is where the true magic of the image service lies.

Image filters

The filter parameter is simply a string, concatenating several filter effects, which in sequential order will be applied to the original image file. Below is a list of available effects:

• block
• blur
• border
• emboss
• grayscale
• invert
• rounded
• sharpen
• rgbadjust
• hsbadjust
• edge
• gamma
• bump
• sepia
• colorize
• hsbcolorize
• rotate90
• rotate180
• rotate270
• fliph
• flipv
• scaleheight
• scalemax
• scalesquare
• scalewide
• scalewidth

When passing the filters concatenated as a parameter to the createImageUrl function, the end result might look like this:

scalewide(300,100);block(5);rounded(5)

Above: Result with custom filter applied to the same image as used earlier

Feel free to post links demonstrating the new image service in action in the comment field below - we appreciate your feedback!