DAM Focal module

Edition

Incubator (services)

Issues

Git

Git

Latest

2.3.1

Compatible with Magnolia 6.2, 6.1, 5.7, 5.6.5.

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:

  • Magnolia 6.2

  • Magnolia 6.1

  • Magnolia 5.7

  • Magnolia 5.6.5

focal-areas
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-area</artifactId>
  <version>2.3.1</version>
</dependency>
focal-point
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-point</artifactId>
  <version>2.3.1</version>
</dependency>
focal-hotspot
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-hotspot</artifactId>
  <version>2.3.1</version>
</dependency>
focal-samples
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-samples</artifactId>
  <version>2.3.1</version>
</dependency>
focal-areas
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-area</artifactId>
  <version>1.1.6</version>
</dependency>
focal-point
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-point</artifactId>
  <version>1.1.6</version>
</dependency>
focal-hotspot
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-hotspot</artifactId>
  <version>1.1.6</version>
</dependency>
focal-samples
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-samples</artifactId>
  <version>1.1.6</version>
</dependency>
focal-areas
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-area</artifactId>
  <version>1.0.13</version>
</dependency>
focal-point
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-point</artifactId>
  <version>1.0.13</version>
</dependency>
focal-hotspot
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-hotspot</artifactId>
  <version>1.0.13</version>
</dependency>
focal-samples
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-samples</artifactId>
  <version>1.0.13</version>
</dependency>
focal-areas
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-area</artifactId>
  <version>1.0.6</version>
</dependency>
focal-point
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-point</artifactId>
  <version>1.0.6</version>
</dependency>
focal-hotspot
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-hotspot</artifactId>
  <version>1.0.6</version>
</dependency>
focal-samples
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-focal-samples</artifactId>
  <version>1.0.6</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 the output format

To change the interpolation algorithm, you can set the following property /modules/imaging/config/generators/focalpoint/operations/outputFormat/@formatName with the wished output format.

To use the original file extension as output format, set the @formatName to original. To change the compression quality, set the @quality to an integer value between 0 and 100.

To apply it for the focal areas, set the same property in /modules/imaging/config/generators/focalpoint/operations/outputFormat/@formatName.

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.

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.

/.imaging

The imaging servlet and the related generator.

/focalarea

The focal area imaging operation.

/1600x900 (*)

The requested size Width x Height.

/dam

The JCR workspace.

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

The asset JCR id.

/magazine.png

The asset name (SEO purpose).

(*) Shortcuts can be used for the size
/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

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

Item Description

magnolia

The context root.

/.imaging

The imaging servlet and the related generator.

/focalpoint

The focal point imaging operation.

/1600x900 (*)

The requested size Width x Height.

/dam

The JCR workspace.

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

The asset JCR id.

/magazine.png

The asset name (SEO purpose).

(*) Shortcuts can be used for the size
/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
The system will return the configuration for the closest configuration. If the system cannot find any focal area, 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

2.3.1

2.3

2.2

2.1

2.0.6

2.0.5

2.0.4

2.0.3

2.0.2

2.0.1

2.0

1.1.6

1.1.4

1.1.3

1.1

Updated for Magnolia 6.0 compatibility.

1.0.13

1.0.12

1.0.11

1.0.10

1.0.9

1.0.8

Fixed bug when uploading new assets

1.0.7

Initial release of the extensions version of the module.

Moved the variation definition from the component level to the DAM level
Feedback