DAM Focal module

Digital asset management (DAM) Incubator

Issues

RESPDAM

Git

Latest

3.0.4

Compatible with Magnolia 6.3.

From version 3.0.4:

The dam-focal incubator module is replaced by the DX Core extension image-focal (also known by the user-friendly name of Image Focal).
The original incubator module dam-focal is renamed to have the user-friendly name DAM Focal to avoid confusion. This documentation is updated to reflect this.
The dam-focal incubator module is now in maintenance mode only and will be deprecated once the officially supported extension is released. No new features will be developed.

If you previously used the incubator and want to move to the supported extension:

Uninstall the dam-focal incubator module.
Update dependency management to use the image-focal extension version:
1. 1.0.x for DX Core 6.3 only when used with DAM 5.0. See the installation instructions in the DAM 5 documentation.
2. 2.0.x for DX Core 6.4.

Existing focal point data is preserved when switching modules.

For migration assistance, free 1-hour support is available from the Incubator team on a first-come, non-SLA basis. Email incubator@magnolia-cms.com to plan.

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.4</version>
</dependency>

focal-point

<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-point</artifactId>
  <version>3.0.4</version>
</dependency>

focal-hotspot

<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-hotspot</artifactId>
  <version>3.0.4</version>
</dependency>

focal-samples

<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-samples</artifactId>
  <version>3.0.4</version>
</dependency>

Usage

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

Configuration

Define the images variations
Limit the size of the images in the editor
Enhance the interpolation algorithm
Define image output and quality
Define the hotspots dialog

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.