loading table of contents...

Studio Developer Manual / Version 2310

Table Of Contents

9.5.3 Image Cropping and Image Transformation

The Image Editor provides various image transformations which are stored in a separate struct property of the content item. It also holds the original image data which is never modified - the transformations are applied only when previewing or delivering the image.

The Image Editor uses the same Image Transformation Framework to display the image within the image form as the CAE uses for delivering images to web sites, for example, within the preview panel. See the Content Application Developer Manual for further details on image transformations.

The ImageEditorPropertyField is defined in the CMPictureForm.ts of the Blueprint and can be defined by using the config properties listed below. Properties marked with * are mandatory.

Config PropertyTypeDescription
bindTo* ValueExpression A property path expression leading to the content Bean whose properties are edited.
propertyName* String The name of the BLOB property containing image data.
imageSettingsPropertyName* String The name of the Struct property containing image transformation data.
hideIssues boolean If true, no validation issues on this property field are shown. Defaults to false.
forceReadOnlyValueExpression String An optional ValueExpression which makes the component read-only if it is evaluated to true.

Table 9.2.  ImageEditorPropertyField Configuration Settings

The ImageEditorPropertyField can be configured as follows:

Config(ImageEditorPropertyField, {
  bindTo: config.bindTo,
  propertyName: "data",
  imageSettingsPropertyName: "localSettings",

Example 9.21. Configuring the Image Editor

A crop is a subset of the image with a fixed aspect ratio and minimum size. Crops in the Image Editor are represented by variants. There are two different ways to configure variants: via Spring or as site specific variants directly in the content.

Spring Configuration for Variants

To configure global variants for all CMPicture content items, beans of type com.coremedia.cap.transform.Transformation can be added to the Spring application context which are automatically picked up by the transformImageService bean. Each variant is defined by one Transformation which holds all the information for that variant.

<bean class="com.coremedia.cap.transform.Transformation">
  <property name="name" value="large4x3"/>
  <property name="widthRatio" value="4"/>
  <property name="heightRatio" value="3"/>
  <property name="minWidth" value="640"/>
  <property name="minHeight" value="480"/>
  <property name="previewWidth" value="400" />

Example 9.22. Configuring an image variant

The configuration of variants via Spring is the default used by the TransformImageService.

Theme Specific Image Variants

In the Blueprint, the image variants are by default defined in the themes of the frontend workspace. The CSS and the templates create the HTML elements with their widths and heights on the website. As such, they are the first choice for placing the image variant settings. Have a look at the Example 5.8, “Responsive Images.settings.json” in Frontend Developer Manual and at the Responsive Images.settings.json files in themes of the Blueprint workspace.

Site-specific Image Variants

If a site does not have a theme and if not all sites should have the same fixed set of image variants, you can configure site-specific image variants via content instead. Define a CMSettings content item named responsiveImageSettings with the struct property linkedSettings for every site (see also Section “Content Configuration” below).

The feature for site-specific variants is enabled by default. To disable it, set the property imagetransformation.dynamic-variants to false.

In addition to the site-specific variants, the default variants configured in the Spring configuration (see Section “ Spring Configuration for Variants ” ) will always be applied.

Rendering Site Specific Image Variants

When rendering images, the TransformImageService is used to access the variants of an image. You can find an example for this in the CMPicture.asPreview.ftl file. In this template, the previewWidth and previewHeight attributes of the Transformation class are used to calculate the image size in the preview. If these attributes are not set, minWidth and minHeight are used instead.

CAE Configuration

For the CAE, the class TransformImageService is responsible for loading site specific cropping information. Disable the feature by configuring imagetransformation.dynamic-variants=false.

The TransformImageService will automatically look up the linked settings of the root channel and search for the "Responsive Image Settings" struct which contains the variant information.

Content Configuration

The "Responsive Image Settings" content item not only contains image variants, but also various resolutions which may be used on different devices. The breakpoint values defined in the CSS for the corresponding theme are used to determine which resolution should be used. With the introduction of site specific image crops, you can configure additional struct properties for variants.

Variant Properties, the following are mandatory:

  • widthRatio: minimum integer which defines the width of the aspect ratio
  • heightRatio: minimum integer which defines the height of the aspect ratio
  • minWidth: this value is the minimum variant width the studio demands while uploading an image (integer property)
  • minHeight: this value is the minimum variant height the studio demands while uploading an image (integer property)

Predefined image sizes (resolutions), at least one pair should be defined per variant and must match the aspect ratio:

  • width: defines the width of the image (integer property)
  • height: defines the height of the image (integer property)

So minWidth and minHeight should at least be as high as the largest predefined image size.

Properties for variant and predefined image sizes (properties listed within the predefined image size properties will always override the more general variant properties):

  • jpegQuality: the default JPEG quality of the picture (string value with numeric value from 0 (excluded) to 1).
  • webpQuality: the default WebP quality of the picture (string value with numeric value from 0 (excluded) to 1). This value is ignored in the built-in image transformation and may only be used with the CoreMedia Image Transformation Service.
  • avifQuality: the default AVIF quality of the picture (string value with numeric value from 0 (excluded) to 1). This value is ignored in the built-in image transformation and may only be used with the CoreMedia Image Transformation Service.
  • sharpen: boolean value to enable/disable sharpening of the picture.
  • removeMetadata:boolean value to enabled/disable metadata removal of the transformed image.

MIME Type Mapping

Another optional setting in the content is a struct property called linkMimeTypeMapping which can be used to adjust the MIME type / file extension of links that are created for image variants. For details see Section 5.4.14, “Images” in Blueprint Developer Manual .

Search Results

Table Of Contents

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.