OpenCms documentation
OpenCms documentation

Image handling

OpenCms integrates a server-side image processing library that is able to apply transformations and filters to images on demand. The image library is especially useful to realize responsive websites: content editors need to upload one image in good quality only—later on, the content editor and also the template developer can decide to deliver certain cutouts of images only or images in different sizes optimized for (mobile) client devices.

The image processing library supports all kinds of image transformations relevant for website building such as scaling, cropping, and filtering. All modern image formats are supported besides the SVG and also not the JPEG 2000 format.

Image processing is possible for large images in a multi-user scenario due to an integrated cache: a transformed image version is processed only when requested for the first time, and is immediately stored to a file system cache. Further requests of the same transformation of an image are then delivered directly from the file system.

How an image should be scaled, can be decided by the content editor as well as the template developer. The OpenCms workplace integrates an image editor where the content editor can crop and scale an image, and also can set a focus point. The template developer can use the available JSP APIs for image processing as described below.

There are two ways of using the image processing library in a JSP. There is a <cms:img> taglib available and a JSP bean called CmsJspImageBean. The <cms:img> tag is easy to use. When developing a new JSP though, it is recommended to use the image bean since it has more features. Especially, applying a chain of transformations to an image is more convenient with the image bean.

You normally get an image bean in a JSP by calling the toImage method on one of the available value wrappers as described below. Each method of the image bean returns the modified bean again, now holding the information on the transformation. Hence, you can chain a whole sequence of these transformations.

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.
Provider class

org.opencms.jsp.util.CmsJspImageBean

EL expression

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

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

With content 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
ib.scaleWidth[{width}]

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

ib.scaleRatio[{ratio}]

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.

ib.scaleHiDpi[{fact}]

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. 

ib.scaler

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.

Responsive images are crucial in modern web design. Besides the <img> tag and its src attribute, the HTML5 language introduces the attribute srcset in the <img> tag where one can define a set of image URLs for different screen sizes and also for high dpi devices (retina displays).

The image bean provides methods to generate and deal with the HTML src attribute as well as the srcset attribute. ib means image bean.

ib.srcUrl

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

ib.imgSrc

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}".

ib.setSrcSets({ib2})

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.

ib.srcSetEntry

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

ib.srcSet

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

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

ib.height

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

ib.width

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

ib.scaled

Returns a flag, indicating if the image is scaled.

ib.image

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