The Image Editor provides various image transformations which are stored in a separate struct property of the document. 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.

The ImageEditorPropertyField can be configured as follows:

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

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 documents, the mediatransform.xml has to be adjusted. 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" />
</bean>
      

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

Site Specific Image Variants

If not all sites should have the same fixed set of image variants, site specific image variants can be configured via content instead. Thereto a CMSettings document named responsiveImageSettings with the struct property linkedSettings has to be defined for every site (see also section "Content Configuration" below).

The feature for site specific variants is enabled by default. To disable it, the property dynamicVariants has to be set to false in the filetransform-image-service.properties.

In addition to the site specific variants, the default variants configured in the mediatransform.xml file will always be applied.

Rendering Site Specific Image Variants

When rendering images, the TransformImageService is used to access the variants of an image. An example for this can be found in the CMPicture.asPreview.ftl. 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. The feature can be enabled by changing/adding the attribute dynamicVariants to true in the file mediatransform.xml. This file is part of the Blueprint so it can be customized if necessary.

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" document 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, additional struct properties can be configured for variants.

Variant Properties, the following are mandatory:

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

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):