OpenCms Documentation

Image handling

 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 11.0.0 Documented since: 11.0.0 Latest revision for: 11.0.0 Valid for OpenCms: 11.0.2

OpenCms supports image scaling on demand, i.e., editors upload one (big) image, but the server delivers scaled versions of the image to the client. The images are scaled when the image is requested for the first timeThen the result is cached, hence delivery will be fast.. How images should be scaled can be selected by the editor and by the template developer, when scaling the image in the JSP.

This topic explains how to use scaling in JSPs. A special focus is on the case of providing source sets of images is discussed.

We use the image bean for scaling images, introduced in OpenCms 11A much simpler version of the bean was present in OpenCms 10.5 already., which is far more flexible and powerful than the <cms:img> tag used before.

Why should I use special image handling in JSPs?

You do not have to use special image handling in JSPs. It's of course possible to to put just <img src="<cms:link>/link/to/my/image</cms:link>" />  into your code. But since OpenCms can scale images on the fly, there's good reason to use specific image handling in JSPs. With just one picture, you can:

  • Provide an image scaled exactly to your needs.
  • Provide a whole source set of images in different resolutions.
  • Deliver only parts of the original image (crop the image) to get the exact ratio you need.
  • Apply filters to the image.

The image bean

Since version 11, OpenCms supports multiple value wrappers. If you know, your content's value holds the link to an image, you can call toImage and get a CmsJspImageBean. It provides a whole bunch of methods to scale your image and to output links for the various scaled version.

Note that scaling/cropping is not supported for SVG images.

Here's a short overview on the bean, how to get it in a JSP and where you find the JavaDoc. Below you, we introduce some interesting methods.

Provider class


EL expression

With content of type CmsJspContentAccessBean (as typical in a formatter):

  • content.value.{XML node name}.toImage

With content of type res of type CmsJspResourceWrapper (as typical, when you read a resource via some EL expression):

  • res.toImage

When accessing element settings where setting is cms.element.setting.{my setting}:

  • setting.toImage

Interesting methods of the bean

The image bean has many options to adjust the scaling parameters for an image. Furthermore, it provides methods to easily output links in the src and srcset attribute of the <img> tag. Below, we introduce only the most interesting methods. Have a look at the JavaDoc for more methods.

We always talk about images in combination with the <img> HTML tag, but of course the bean is equivalently useful in combination with the HTML tag <picture>.

Scaling, cropping, squezing

OpenCms allows for multiple image transformations. Here we list some of them and how to use them at the bean. Each method returns the modified bean again, now holding the information on the transformation. Hence, you can chain a whole sequence of these transformations. We call the attribute holding the image bean ib.

All scaling operations are performed based on the original image when finally the image link is requested. That means in particular hi dpi versions of a formerly down-scaled image are not the up-scaled versions of the down-scaled image, but also (in the best case) down-scaled versions of the original image. Hence there is no quality issue here.
Transformation methods of the image bean (incomplete)

Scales the image to the provided width, wher {width} should be the target width in pixels, e.g., 400.


Scales the image to the provided ratio, changing the height of the image, not the width. A ratio should have format, e.g., {ratio} could be 4-3, or 2.35-1 or 1,4-3,1.


Returns the high dpi version of the current image, e.g., scales it with the provided scaling factor (width and height). The scaling factor is given as number followed by 'x', e.g., {fact} can be 2x or 2.5x


Returns the CmsImageScaler that is used for scaling the image. Here any possible transformation can be added and will be applied to the image. Note that this method can't be chained, since the return value is not an image bean.

Dealing with source sets

Modern websites need to be able to handle images according to the used screen size to prevent unnecessarily large images on small devices. HTML5 provides the attribute srcset in the tag <img>, into which you insert a set of images from which the browser chooses the image with the appropriate resolution. To manage an image on a fully responsive website, you have to create a set of images. Usually, the image is scaled for five different screen sizes and also for high dpi devices (retina displays).

The image bean provides methods to generate and deal with the source sets. Below, ib is the image bean.

Methods for dealing with source sets (incomplete)

Adds the image bean {ib2} to the source set stored in the image bean ib. You can use this setter in EL as follows:
    <c:set target="${ib}" property="srcSets" value="${ib.scaleWidth[250]}" />
to add a scaled version of the current image wrapped by the current bean to the source set.


The correct source set entry for the currently wrapped image as string, i.e., "{image url} {image width}w".


The source set wrapped by the image bean as string in the format required by the srcset attribute of the <img> tag.

Getting information on the image

The bean provides access to meta information on the wrapped image, here are some of the provided methods.

Accessing meta information of the wrapped image (incomplete)

Returns the original height of the (possibly scaled) image.


Returns the original width of the (possibly scaled) image.


Returns a flag, indicating if the image is scaled.


Returns a flag, indicating if an image is wrapped at all. If this is false, the bean has not been initialized correctly.

Getting the URLs into the HTML code

In general, all you would need is to get the URL to the scaled image, but the bean provides some more convenience methods.

Methods for rendering the image urls and extra information (incomplete)

Returns the link to the image as to put it in the src attribute of the <img> tag. Identically to ${ib}.


Returns the attributes for the <img> tag specific for the wrapped image, i.e., the string src="{image url}" width="{real width of the (scaled) image}" height="{real height of the (scaled) image}".


The correct source set entry for the currently wrapped image as string, i.e., "{image url} {image width}w".


The source set wrapped by the image bean as string in the format required by the srcset attribute of the <img> tag.

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.