Page tree
Skip to end of metadata
Go to start of metadata

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)


Installation

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

<!-- To install the focal areas module -->
<dependency>
    <groupId>info.magnolia.dam</groupId>
    <artifactId>magnolia-dam-focal-area</artifactId>
    <version>${dam-focal.version}</version>
</dependency>

<!-- To install the focal point module -->
<dependency>
    <groupId>info.magnolia.dam</groupId>
    <artifactId>magnolia-dam-focal-point</artifactId>
    <version>${dam-focal.version}</version>
</dependency>

<!-- To install the focal hotspot module -->
<dependency>
    <groupId>info.magnolia.dam</groupId>
    <artifactId>magnolia-dam-focal-hotspot</artifactId>
    <version>${dam-focal.version}</version>
</dependency>

<!-- To install the samples module -->
<dependency>
    <groupId>info.magnolia.dam</groupId>
    <artifactId>magnolia-dam-focal-samples</artifactId>
    <version>${dam-focal.version}</version>
</dependency>

Versions

2.0.6Magnolia 6.2
1.1.6Magnolia 6.1
1.0.13

Magnolia 5.7

1.0.6Magnolia 5.6.5

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.

dam-focal-common
dam-focal-common:
  config:
    variations:
      Cinema:
        description: Cinema
        minHeight: 120
        minWidth: 213
        ratio: 16/9
      Wide:
        description: Cinema wide
        minHeight: 120
        minWidth: 280
        ratio: 21/9
      Square:
        description: Square
        minHeight: 120
        minWidth: 120
        ratio: 1/1


Properties:

minHeight

optional, required if minWidth is not set

The minimum height of the focal area in pixel.

minWidth

optional, required if minHeight is not set

The minimum width of the focal area in pixel.

ratio

The display ratio of the focal area.

description

optional

Used in the DAM detail subapp


Limit the size of the images in the editor

By default, the max width and the max height of the images in the editor are respectively 1024px and 768px. You can change these values as following:

dam-focal-common
dam-focal-common:
  config:
    editorConfig:
      mediaEditorMaxWidth: 400
      mediaEditorMaxHeight: 300
      editorMaxWidth: 684
      editorMaxHeight: 513


Properties:

mediaEditorMaxWidth

optional

The maximum image width allowed in the editor for the focal areas.

mediaEditorMaxHeight

optional

The maximum image height allowed in the editor for the focal areas.

editorMaxWidth

optional

The maximum image height allowed in the editor for the focal points/hotspots.

editorMaxHeight

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 hotspots dialog

You can define per DAM folder which dialog should be attached to the hotspots. The system will always take the longest matching path.


dam-focal-hotspot
dam-focal-hotspot:
  config:
    mapping:
      default:
        dialog: headless-ecommerce:focal/default
        path: '/'
      product:
        dialog: headless-ecommerce:focal/product
        path: '/products'


Build the image URL for the focal area

Examples: 

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

The context root

/.imagingThe imaging servlet and the related generator
/focalareaThe focal area imaging operation
/Wide

optional

The screen variation to use

/1600x900 The requested size Width x Height
/damThe JCR workspace
/jcr:aa26dabe-cdfc-4f4d-9f4a-6e1e1327806e The asset JCR id
/magazine.pngThe asset name (SEO purpose)

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

magnolia

The context root

/.imagingThe imaging servlet and the related generator
/focalpointThe focal point imaging operation
/1600x900 The requested size Width x Height
/damThe JCR workspace
/jcr:aa26dabe-cdfc-4f4d-9f4a-6e1e1327806e The asset JCR id
/magazine.pngThe asset name (SEO purpose)

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

Example of json response:

response.json
"image":{
      "@name":"creatv-eight-unsplash.jpg",
      "@path":"/inspirations/heroes/creatv-eight-unsplash.jpg",
      "@id":"jcr:59f76215-bbdd-4275-9e46-af089c3f67a7",
      "@link":"/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg",
      "metadata":{
         "fileName":"creatv-eight-unsplash.jpg",
         "mimeType":"image/jpeg",
         "fileSize":"1671300",
         "height":"1186",
         "width":"1801",
         "format":"image/jpeg",
         "creator":[
            "superuser"
         ],
         "date":"2020-07-14T11:34:12.743+02:00",
         "created":"2020-06-30T22:13:08.335+02:00",
         "modified":"2020-07-14T11:34:12.743+02:00"
      },
      "focal":{
         "hotspots":[
            {
               "left":47.22222222222222,
               "top":63.55555555555556,
               "title":"Point 3"
            },
            {
               "left":31.871345029239766,
               "top":12.0,
               "title":"Point 1"
            },
            {
               "left":68.71345029239767,
               "top":10.0,
               "title":"Point 2"
            }
         ],
         "point":{
            "left":80.11695906432749,
            "top":52.22222222222222,
            "urls":{
               "auto":"/.imaging/focalpoint/_WIDTH_x_HEIGHT_/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg",
               "TabletPortrait":"/.imaging/focalpoint/TabletPortrait/_WIDTH_x_HEIGHT_/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg",
               "TabletLandscape":"/.imaging/focalpoint/TabletLandscape/_WIDTH_x_HEIGHT_/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg",
               "Wide":"/.imaging/focalpoint/Wide/_WIDTH_x_HEIGHT_/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg",
               "PhoneLandscape":"/.imaging/focalpoint/PhoneLandscape/_WIDTH_x_HEIGHT_/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg",
               "Square":"/.imaging/focalpoint/Square/_WIDTH_x_HEIGHT_/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg",
               "Cinema":"/.imaging/focalpoint/Cinema/_WIDTH_x_HEIGHT_/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg",
               "PhonePortrait":"/.imaging/focalpoint/PhonePortrait/_WIDTH_x_HEIGHT_/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg"
            }
         },
         "areas":{
            "Cinema":{
               "url":"/.imaging/focalarea/Cinema/_WIDTH_x_HEIGHT_/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg",
               "width":1801,
               "height":1013,
               "left":0,
               "top":172
            },
            "auto":{
               "url":"/.imaging/focalarea/_WIDTH_x_HEIGHT_/dam/jcr:59f76215-bbdd-4275-9e46-af089c3f67a7/creatv-eight-unsplash.jpg"
            }
         }
      }
   }

For the hotspot and focal point modules, the left and top positions are percentages of the width and the height.
For legacy reason, the focal area module still store the area coordinates in pixels (from the original picture size).

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

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


Warnings

  • This module is at INCUBATOR level.

Changelog

  • Version 2.0.6
  • Version 2.0.5
  • Version 2.0.4
  • Version 2.0.3
  • Version 2.0.2
  • Version 2.0.1
  • Version 2.0
  • Version 1.1.6
  • Version 1.1.4
  • Version 1.1.3
  • Version 1.1
    • Updated for Magnolia 6.0 compatibility.
  • Version 1.0.13
  • Version 1.0.12
  • Version 1.0.11
    • RESPDAM-8 - Getting issue details... STATUS
  • Version 1.0.10
    • RESPDAM-5 - Getting issue details... STATUS
  • Version 1.0.9
  • Version 1.0.8
    • Fixed bug when uploading new assets
  • Version 1.0.7 - Initial release of the extensions version of the module.
    • Moved the variation definition from the component level to the DAM level

2 Comments

  1. I see that areas is marked as "legacy" "Focal areas: (Legacy)". Should this feature not be recommended or promoted then?

  2. Actually, the feature will still be maintained. We have requests for both focal area and focal point.