Configure

Configure image variations first, then set up editor settings, image processing, and integrations as needed.

Image variation configuration

Start by configuring the variation sets according to the screen resolutions you want to target.

Define the image variations

Here’s a sample variation configuration.

To define your own variations, decorate the following configuration: /your_module/decorations/image-focal-common/config.yaml.

variations: !override (1)
  Cinema:
    description: Cinema (2)
    minHeight: 120 (3)
    minWidth: 213 (4)
    ratio: 16/9 (5)
    allowedWidths: (6)
      - 400
      - 800
      - 1200
      - 1600
  Wide:
    description: Cinema wide
    minHeight: 120
    minWidth: 280
    ratio: 21/9
    allowedWidths:
      - 400
      - 800
      - 1200
      - 1600
  Square:
    description: Square
    minHeight: 120
    minWidth: 120
    ratio: 1/1
    allowedWidths:
      - 400
      - 800
      - 1200
      - 1600

1	Add the `!override` keyword to replace the default variations that come with the module.
2	optional Used in the DAM detail subapp.
3	optional required if minWidth is not set The minimum height of the focal area in `px`.
4	optional required if minHeight is not set The minimum width of the focal area in `px`.
5	required The display ratio of the focal area.
6	optional The list of allowed widths. This helps limit the number of generated images. If another width is explicitly set or computed, the rendered image width is set to the closest upper value in the list, or to the maximum value if the input width exceeds it. The height is set to match the variation ratio.

Editor configuration

Configure size limits for images in the editor and define dialogs for hotspot management.

Limit the size of the images in the editor

To define your limits, decorate the following configuration: /your_module/decorations/image-focal-common/config.yaml.

editorConfig:
  mediaEditorMaxWidth: 400 (1)
  mediaEditorMaxHeight: 300 (2)
  editorMaxWidth: 684 (3)
  editorMaxHeight: 513 (4)

1	optional The maximum image width allowed in the editor for focal areas.
2	optional The maximum image height allowed in the editor for focal areas.
3	optional The maximum image width allowed in the editor for focal points/hotspots.
4	optional The maximum image height allowed in the editor for focal points/hotspots.

Define the hotspot dialog

The image-focal-hotspot module provides a default hotspot dialog that you can use:

config.yaml

mapping:
  default:
    dialog: image-focal-hotspot:focal/default
    path: '/'

The system uses the focal/default dialog from the image-focal-hotspot module by default. You can customize this dialog or create your own and reference it in the configuration above:

default.yaml

label: Focal Hotspot
form:
  properties:
    title:
      label: Title
      $type: textField
      i18n: true

You can decorate the configuration as shown below. This configuration uses the focal/product dialog defined in your light module for all assets in the /products folder.

/your_module/decorations/image-focal-hotspot/config.yaml

mapping:
  product:
    dialog: your_module:focal/product
    path: '/products'

The system picks the dialog that best matches the path defined in the mapping. For example, the asset /homepage/banner.png matches the default mapping, while the asset /product/table.png matches the product mapping.

Image processing configuration

Configure interpolation algorithms and output formats to control image quality and performance.

Enhance the interpolation algorithm

To change the interpolation algorithm, set the following property: /modules/imaging/config/generators/focalpoint/operations/resize@interpolation with one of these values:

nearest_neighbor: Fastest but least precise
bilinear: Slower and more precise [default]
bicubic: Slowest and most precise

To apply this setting to focal areas, set the same property in /modules/imaging/config/generators/focalarea/operations/resize@interpolation.

Define image output and quality

By default, the image format is webp and the quality is 100.

You can change these defaults by decorating the appropriate config.yaml file.

DAM Focal Area
DAM Focal Point

image-focal-area/decorations/imaging/config.yaml

generators:
  focalarea:
    class: info.magnolia.dam.focal.imaging.DamFocalOperationChain
    outputFormat:
      quality: 100 (1)
      formatName: jpg (2)

1	Where `quality` is an integer between `0` and `100`, with `0` being the lowest and `100` being the highest quality retention.
2	Where `formatName` is the format for your image such as `webp`, `jpg`, or `png`. For more on format types, see Output format.

For more details, see config.yaml.

image-focal-point/decorations/imaging/config.yaml

generators:
  focalpoint:
    class: info.magnolia.dam.focal.imaging.DamFocalOperationChain
    outputFormat:
      quality: 100 (1)
      formatName: png (2)

1	Where `quality` is an integer between `0` and `100`, with `0` being the lowest and `100` being the highest quality retention.
2	Where `formatName` is the format for your image such as `webp`, `jpg`, or `png`. For more on format types, see Output format.

For more details, see config.yaml.

Integration configuration

Set up renderers, REST clients, and templating functions to integrate the module with your Magnolia installation.

FocalPointRenderer

You can use the standard Magnolia mechanisms (such as DAM template functions and the pages delivery endpoint) while keeping the focal point functionality. To do this, you must set the FocalPointRenderer as the renderer for the jcrProvider.

/decorations/dam/config.yaml

providers:
  jcrProvider:
    renderers:
      imaging:
        class: info.magnolia.dam.focal.renderer.FocalPointRenderer

Additionally, you must configure the renditions that you want to render with the FocalPointRenderer. If a rendition is not configured, it uses the default renderer ImagingBasedAssetRenderer. To configure a rendition:

/decorations/image-focal-common/config.yaml

focalPointRenditionDefinitions:
 - name: square (1)
   width: 240
   height: 240
 - name: 480x360 (2)
 - name: unknown (3)

1	When an asset uses the rendition `square`, it uses the `FocalPointRenderer`, generating a link such as `/magnolia/.imaging/focalpoint/240x240/dam/jcr:jcr-id/name.jpg`.
2	When an asset uses the rendition `480x360`, it uses the `FocalPointRenderer`, generating a link such as `/magnolia/.imaging/focalpoint/480x360/dam/jcr:jcr-id/name.jpg`.
3	When an asset uses the rendition `unknown`, it won’t use the `FocalPointRenderer` but the default renderer, because the dimensions of the image are unknown.

When width or height are not configured, the renderer tries to infer the dimensions of the rendition. If a rendition is configured to use the FocalPointRenderer and it has no dimensions configured or the rendition is not compatible with dynamic dimensions, then it uses the default renderer.

You can disable a rendition by adding the property disabled: true.

Build the image URL for the focal area

Use these URL patterns to generate focal images with specific dimensions and variations.

Example: /magnolia/.imaging/focalarea/1600x900/dam/jcr:aa26dabe-cdfc-4f4d-9f4a-6e1e1327806e/magazine.png
Example: /magnolia/.imaging/focalarea/Wide/1600x900/dam/jcr:aa26dabe-cdfc-4f4d-9f4a-6e1e1327806e/magazine.png

Item Description

magnolia

The context root.