Blueprint Developer Manual / Version 2110
Table Of ContentsRequirements
For a website, images are required in different sizes and formats. For example, teaser need a small image with an aspect ratio of 1:1 in the sidebar and an aspect ratio of 4:3 in the main section. Images in articles and galleries are shown in 5:2 or 4:3 with a large size. And even these sizes are different on mobile devices and desktop displays.
Solution
CoreMedia Blueprint supports different formats combined with different sizes. It comes with four predefined cropping definitions.
- portrait_ratio3x4 (aspect ratio of 3:4)
- portrait_ratio1x1 (aspect ratio of 1:1)
- landscape_ratio4x3 (aspect ratio of 4:3)
- landscape_ratio16x9 (aspect ratio of 16:9)
A list of sizes can be defined for each format in the Responsive Image Settings
which are usually
defined in the settings of a site's theme as described
in Frontend Developer Manual.
They can also be located in the Options/Settings/CMChannel
folder of the site, in the global settings below /All Content/Settings/Options/Settings
or
in the Spring configuration in the backend server. For more details
see Section 9.5.3, “Image Cropping and Image Transformation” in Studio Developer Manual.
The website will automatically choose the best matching image depending on the viewport of the client's browser.
How to configure image sizes
The struct responsiveImageSettings
contains a list of string properties. This
string must contain the name of a cropping format. For example portrait_ratio1x1
.
Each format contains a list of string properties, representing one size of this format. The name
and the order of this list is not important and will be ignored. Every size must contain two
integer properties width
and height
.
If site specific image variants are enabled, the Responsive Image Settings
will be
used for the image editor as well. In this case the additional integer property fields
widthRatio
, heightRatio
, minWidth
and
minHeight
must be defined. Additionally, the field previewWidth
and/or
previewHeight
should be defined to define the preview size in Studio.
For example a Responsive Image Settings
with two formats.
portrait_ratio1x1
with just one size and landscape_ratio4x3
with three sizes.
<Struct xmlns="http://www.coremedia.com/2008/struct"> <StructProperty Name="responsiveImageSettings"> <Struct> <StructProperty Name="portrait_ratio1x1"> <IntProperty Name="widthRatio">1</IntProperty> <IntProperty Name="heightRatio">1</IntProperty> <IntProperty Name="minWidth">200</IntProperty> <IntProperty Name="minHeight">200</IntProperty> <IntProperty Name="previewWidth">400</IntProperty> <StringProperty Name="jpegQuality">0.8</StringProperty> <Struct> <StructProperty Name="0"> <Struct> <IntProperty Name="width">60</IntProperty> <IntProperty Name="height">60</IntProperty> </Struct> </StructProperty> </Struct> </StructProperty> <StructProperty Name="landscape_ratio4x3"> <IntProperty Name="widthRatio">4</IntProperty> <IntProperty Name="heightRatio">3</IntProperty> <IntProperty Name="minWidth">1180</IntProperty> <IntProperty Name="minHeight">885</IntProperty> <IntProperty Name="previewWidth">400</IntProperty> <StringProperty Name="jpegQuality">0.7</StringProperty> <Struct> <StructProperty Name="0"> <Struct> <IntProperty Name="width">200</IntProperty> <IntProperty Name="height">150</IntProperty> </Struct> </StructProperty> <StructProperty Name="1"> <Struct> <IntProperty Name="width">320</IntProperty> <IntProperty Name="height">240</IntProperty> </Struct> </StructProperty> <StructProperty Name="2"> <Struct> <IntProperty Name="width">640</IntProperty> <IntProperty Name="height">480</IntProperty> </Struct> </StructProperty> </Struct> </StructProperty> </Struct> </StructProperty> </Struct>
Caution
Every image cropping format must contain one image size, otherwise the default size and
format, defined in ImageFunctions
, will be used.
Image dimensions supported in Cloud Installations
The editing capabilities of Self-Managed and new Cloud Installations since CMCC 11 (2307) differ in terms of
supported image formats, image sizes, and image editing capabilities. The image dimensions supported in
Cloud installations are listed
here.
Make sure that the sizes defined in the Responsive Image Settings
match the supported
dimensions.
High Resolution/Retina Images
CoreMedia Blueprint supports high resolution images. Set the
BooleanProperty enableRetinaImages
to true. If enabled, the JavaScript
jquery.coremedia.responsiveimages.js
is choosing a larger image according to the
devicePixelRatio
of the browser.
For Example the website wants to render an image with an aspect ratio of 4:3 and the best
responsive image size is 400px : 300px
. With a devicePixelRatio
of 2,
the JavaScript jquery.coremedia.responsiveimages.js
is now choosing the size of
800px : 600px
.
Default JPEG Compression Quality
The default JPEG compression quality is 80% in CoreMedia Blueprint.
This parameter is configured in blueprint-handlers.xml
for the
transformedBlobHandler
. For further information consult the "CAE Application
Developer Manual", chapter "Image Transformation API".
MIME Type Mapping
When building links to image variants in the CAE, the MIME type of the original image is used by default
to determine the file extension of the links.
To adjust these MIME types you can provide a mapping of original MIME types to desired MIME types
in the setting linkMimeTypeMapping
.
The struct linkMimeTypeMapping
contains String properties where the key is the MIME type of the
original image and the value is the desired MIME type for the links to variants of this image.
You could for instance add this setting to the Responsive Image Settings
content item next to the
responsiveImageSettings
struct like so:
<Struct xmlns="http://www.coremedia.com/2008/struct"> <StructProperty Name="linkMimeTypeMapping"> <Struct> <StringProperty Name="image/jpeg">image/png</StringProperty> <StringProperty Name="image/gif">image/png</StringProperty> </Struct> </StructProperty> <StructProperty Name="responsiveImageSettings"> <Struct> <StructProperty Name="portrait_ratio1x1"> ... </StructProperty> ... </Struct> </StructProperty> </Struct>
With these settings all links to variants of images with MIME type image/jpeg
or image/gif
would be created with MIME type image/png
and the file extension .png
instead.