Image Focal module

Issues

Git

Git

Latest

3.0.2

Compatible with Magnolia 6.3.

This module offers different focal features:

Focal areas

(Legacy) Allow the editors to choose the areas of the images to display per screen ratio

Focal point

Allow the editors to choose the focal point on the original image

Focal hotspot

Allow the editors to define hotspots on their images and to attach any type of field(s)

This module is at the INCUBATOR level.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

focal-areas
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-area</artifactId>
  <version>3.0.2</version>
</dependency>
focal-point
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-point</artifactId>
  <version>3.0.2</version>
</dependency>
focal-hotspot
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-hotspot</artifactId>
  <version>3.0.2</version>
</dependency>
focal-samples
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-samples</artifactId>
  <version>3.0.2</version>
</dependency>

Usage

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

Configuration

Define the images variations

Here is a sample of a variation.

To define your own variations, you can decorate the following configuration /your_module/decorations/dam-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 In order to replace the default variations shipped with the module, add the !override keyword.
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. It helps for limiting the number of generated images. If another width is explicitly set or computed, rendered image width will be set to the closest upper value of the list, or to the max value of the list in case input width exceeds it. The height will be set to match the variation ratio.

Limit the size of the images in the editor

To define your limits, you can decorate the following configuration /your_module/decorations/dam-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 the focal areas.
2 optional The maximum image height allowed in the editor for the focal areas.
3 optional The maximum image height allowed in the editor for the focal points/hotspots.
4 optional The maximum image height allowed in the editor for the focal points/hotspots.

Enhance the interpolation algorithm

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

  • nearest_neighbor: Fastest but least precise

  • bilinear: Slower and more precise [default]

  • bicubic: Slowest and most precise

To apply it for the 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

dam-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.
dam-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.

Define the hotspots dialog

A default hotspot dialog is already predefined as below from dam-focal-hotspot module:

config.yaml
mapping:
  default:
    dialog: dam-focal-hotspot:focal/default
    path: '/'

It uses a default dialog focal/default from dam-focal-hotspot module which can also be decorated, or you can create your own dialog and reference it in above config:

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

You can decorate the config as below for instance. It would use the focal/product dialog defined in your light module for all assets residing within /products folder.

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

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

The system will pick the dialog which matches the most the path defined in the mapping. For instance, the following asset /homepage/banner.png will match the default mapping. The following asset /product/table.png will match the product mapping.

FocalPointRenderer

You can use the standard mechanisms in Magnolia (e.g., dam template functions, the pages delivery endpoint) and retain the focal point functionality. To do so, 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 will use the default renderer ImagingBasedAssetRenderer. To configure a rendition:

/decorations/dam-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 would use 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 would use 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.

Notice that 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

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.

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

/.imaging

The imaging servlet and the related generator.

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

/focalarea

The focal area imaging operation.

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

/VARIATION_NAME

optional The focal area operation name.

The "variation name" represents a variant from the configuration such as wide or cinema.

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

/1600x900

The requested size Width x Height.

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

Shortcuts can be used for sizing:

  • /1600x : The Height is computed from passed /Widthx and variation ratio

  • /x900 : The Width is computed from passed /xHeight and variation ratio

  • /original : the original image is returned without any transformation

/dam

The JCR workspace.

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

/jcr:aa26dabe-cdfc-4f4d-9f4a-6e1e1327806e

The asset JCR id.

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

/magazine.png

The asset name (SEO purpose).

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

The system will return the configuration for the closest configuration. If the system cannot find any focal area, then it returns the original picture.

If you provide the screen variation, the system will then use the one you request.

Build the image URL for the focal point

Example

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

Example

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

Item Description

magnolia

The context root.

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

/.imaging

The imaging servlet and the related generator.

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

/focalpoint

The focal area imaging operation.

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

/VARIATION_NAME

optional The focal point operation name.

The "variation name" represents a variant from the configuration such as wide or cinema.

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

/1600x900

The requested size Width x Height.

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

Shortcuts can be used for sizing:

  • /1600x : The Height is computed from passed /Widthx and variation ratio

  • /x900 : The Width is computed from passed /xHeight and variation ratio

  • /original : the original image is returned without any transformation

/dam

The JCR workspace.

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

/jcr:aa26dabe-cdfc-4f4d-9f4a-6e1e1327806e

The asset JCR id.

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

/magazine.png

The asset name (SEO purpose).

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

The system will return the configuration for the closest configuration. If the system cannot find any focal point, then it returns the original picture.

Configure your REST client

In your rest client definition, add an asset resolver on the wished properties.

In order to get the focal data, you will need to set the implementationClass to info.magnolia.dam.focal.rest.reference.AssetFocalReferenceResolver.
rest-client
references:
  - name: assetReference
    propertyName: image
    referenceResolver:
      class: info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition
      implementationClass: info.magnolia.dam.focal.rest.reference.AssetFocalReferenceResolver

Templating functions

The module provides 3 templating functions:

  • damfafn: Provide helper on the focal areas

  • damfpfn: Provide helper on the focal point

  • damfhfn: Provide helper on the focal hotspots

You can find examples for each of them in the magnolia-dam-focal-samples project.

Limitations

Animated gifs are not processed by the focal point module, the system will always return the original version stored in the DAM.

Changelog

The Changelog covers all updates related to this module.

Version Notes

3.0.2

3.0.1

3.0.0

  • Initial release (Magnolia 6.3 support)

  • Changelog

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Image Focal module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules