Developing with the Contensis Image API
The 11.3 release has been largely based around improving the experience of using images in Contensis. Content authors can now easily upload, crop, and publish images. Admins can restrict the size and orientation these are delivered at. But what about developers?
Introducing the new Image API
Our new Image API gives developers more control over how images are rendered to the front-end, no matter the device. This API improves massively over the previous cached image handler, and can deliver images a fraction of their original size but without a significant loss of quality.
The Image API applies transformations in real time and caches the results for fast delivery.
It allows you to:
- Resize and crop
- Rotate and flip
- Apply grayscale and blur effects
- Change the format of the image
- Set the level of compression
These are applied by adding a query string to the URI of the image. For example:
Combining the Image API with the new features of the image editor in Contensis gives you much more control over how images are displayed. You can make full use of the
srcset attribute to deliver the appropriate size and resolution image to any device. Authors can select different creative crops of the same image to be displayed on desktop and mobile.
You resize an image by appending the
height (or both) parameter to the image query string. This allows an author to upload a large high-resolution image while giving the developer an easy way to serve it at an appropriate size for the device or situation in which it's displayed.
crop parameter controls how the image is cropped, scaled, and aligned. Crops can be from top, right, bottom, centre or set manually with specific coordinates. More details can be found in the Image API crop documentation.
The format parameter allows the conversion of one image format to another. Allowed values are
Image quality is controlled by the quality parameter. A value between 0 and 100 sets the compression level.
Images served with the image API are set to be cached for a year, meaning they don’t have to be re-downloaded every time the user visits the site. Contensis adds a unique hash to the file name so if the image changes the browser will not serve the old one. Read more about Image API caching.
Advanced examples of using the Image API
We designed the Image API to support a number of modern development techniques.
Automatically setting an image to resize using srcset
Even if an image has been saved in Contensis at full size, it can be processed and delivered to the browser at the optimum size for the device or connection speed.
srcset attribute, an image can be displayed at different sizes depending on the device size and resolution.
Creating an image component and using the picture element
Using a simple component in Contensis, you can allow an editor to create 3 different crops of the same image and use the
picture element to display them. This is especially powerful as it allows an editor to artistically crop an image to best fit the device or aspect ratio it’s displayed in.
In your code, you can then use the
picture element to display a different image depending on the available space. Here’s an example:
Using a modern web format
WebP is a modern image format developed by Google. WebP images are generally around 25-34% smaller than a comparable JPEG image. This means they load quicker and use less data than older formats.
WebP is a relatively new format and isn’t supported by all browsers (WebP compatibility chart). The Image API detects if the browser is compatible and will serve a standard JPEG if it isn’t.
Try it now!
The Image API is available in Contensis 11.3 and higher and can be easily applied to any image served by Contensis. Just add the query string to any image in your templates, Razor views, or React apps to serve higher quality, better optimised images in a modern format.
Check out the full Image API documentation.