Image Resizing and Processing - Documentation topics on: cache,displaying thumbnail images,display resized images,enterprise only,file assets,filter,image,image filter,image handling,inode,resizing binary image files,.

Image Resizing and Processing

dotCMS includes an image editor - a great tool for content editors to manipulate uploaded images. But almost important is that underlying the image editor is a RESTful interface for manipulating images stored in dotCMS.

Important Notes:

  • The image editor, including the RESTful image editing functions, are only available in dotCMS Enterprise editions.
    • If you use image filters in image URLs with dotCMS Community edition, the images will still be displayed but the filters will not be applied to the images.
  • The order in which the filters are applied is important.
    • The filters will be applied in the order they appear in the URL (filters which appear to the left will be applied first).
    • If you apply multiple filters and the result is not what you expect, try changing the order of the filters.
    • In particular the Jpeg filter (e.g. `/Jpeg`) must be applied last (to the right of all other filters).
      • This is because all filters except the Jpeg filter only work on PNG images, and result in a PNG image, so other filters will not work if they follow conversion to Jpeg format.
  • The image editor and image editing filters do not work with SVG images.

All functions in the image editor can be called via a cacheable URL, which is very helpful and important to web developers looking to automatically resize or edit images for use in your web sites and widgets.

The way it works is the image passes through a series of filters, each of which can take 0 or more parameters. The resultant modified image is then passed through the next filter for processing.

Important to note : the resultant image is generated once and then cached on the dotCMS server for performance.


/contentAsset/{exporter}/{content identifier / inode}/{field velocityVar}/{byInode [1|0]}/{exporter specific parameters}

The base pattern for image handling is as above - it starts with the "exporter", which specifies the base action for the file processing. dotCMS ships with 4 base exporters (you can write custom exporters if these do not suit your purpose).  After that, files can be specified by their identifier (to use the latest live version) or by inode (to use an image tied to a specific version).  If you specify an image by inode, you must pass the "byInode/1" url parameter to identify it as an inode to dotCMS.  After that, depending on your exporter, you can specify various transformations and or patterns.


ImageFilterExporter: /contentAsset/image/....

Allows you to specify different filters to be applied to an image.  Filters include: Crop, Exposure, Flip, Gamma, Gif, Grayscale, Hsb, Jpeg, Png, Resize, Rotate, Scale and Thumbnail.  Filters can be chained for more complex transformations.

In each of the following examples two API methods are shown- the first for manipulating a File Asset that is uploaded and stored to a Site Browser folder and may be associated with a piece of content via an image/file field, and the second for displaying an image that is stored in a binary field INSIDE a piece of content itself. The binary field pathing method includes the velocity variable of the image field (in this case "diagram1"), to reference the right binary image stored inside a piece of content.

crop_x (int) for left of crop
crop_y (int) for top of crop
crop_w (int) for width of crop
crop_h (int) for height of crop
A) File Asset (Stored on Site Browser Tree):
B) Binary File (Stored IN Content):

Exposure: (exposure_exp (double) between 0 and 5.0)
A) File Asset:
B) Binary File:

Flip: (flip_flip 1 or 0)
A) File Asset:
B) Binary File:

Gamma: (gamma_g double value between 0 and 3.0)
A) File Asset:
B) Binary File:

Gif (converts an image to a gif):
A) File Asset:
B) Binary File:

A) File Asset:
B) Binary File:

Hsb: (Hue, Saturation, Brightness)
hsb_h hue (double) between -1.0 and 1.0
hsb_s saturation (double) between -1.0 and 1.0
hsb_b brightness (double) between -1.0 and 1.0
A) File Asset:
B) Binary File:

> Jpeg: (jpeq_q specifies quality, if not defined defaults to 85)
A) File Asset:
B) Binary File:

A) File Asset:
B) Binary File:

A) File Asset:
B) Binary File:

Rotate: (rotate_a for angle (double) 0.00-359.99 degrees to rotate)
A) File Asset:
B) Binary File:

Scale: (scale_w width, scale_h height)
A) File Asset:
B) Binary File:

thumbnail_w (int) specifies width
thumbnail_h (int) specifies height
thumbnail_bg (int) must be 9 digits of rgb (000000000=black, 255255255=white) for background color
A) File Asset:
B) Binary File:

Chained Filter: 
This example shows how multiple filters can be executed in a chain for complex effects.  In this case, the image has been Cropped, then rotated, then the Hue has been modified.  Filters are executed in the order they are listed in the URL: 
A) File Asset:,Rotate,Hsb/crop_w/263/crop_h/155/crop_x/112/crop_y/18/rotate_a/45.0/hsb_h/-0.4/hsb_s/0.00/hsb_b/0.00
B) Binary File:,Rotate,Hsb/crop_w/263/crop_h/155/crop_x/112/crop_y/18/rotate_a/45.0/hsb_h/-0.4/hsb_s/0.00/hsb_b/0.00

ImageResizeFieldExporter: /contentAsset/resize-image/...

resize-image. Resizes a given image to the requested width and height.
Parameters: w, h

ImageThumbnailFieldExporter: /contentAsset/image-thumbnail/....

Generates a thumbnail a given image to the requested width and height dimensions.
Parameters: w,h,bg

RawFieldExporter: /contentAsset/raw-data/....

Exports the file on a given contentlet field as it is.

Cache Busting

dotCMS URI based image tools allow for images to be cached in a user's browser, in a proxy server or by a CDN, all of which can increase a site's performance.  The downside is that it is difficult to keep those caches updated as images change or are edited in dotCMS, and such caches can serve a user a stale version of an image.  To prevent a stale image from being served from the cache, append the image's inode (version id) to the image URI.  Doing this will not affect the image's cacheability or how it's displayed, since dotCMS will ignore any URI parameters that it does not understand.  But the URL will be automatically updated when a new version of the image is published, since the new version id of the image will cause the URL to change.  

So, for this resized image:

You could append:

where v/461b2fa3-fb97-442e-b9ca-19e96d683f65 is the {inode} of the image.  The result is the same to caches and to the end user and it will automatically be updated when a new version of the image is uploaded.