Image Focal module
Edition |
Incubator (services) |
||
Issues |
|||
Git |
|||
Latest |
2.4.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:
<dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-area</artifactId>
<version>2.4.5</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-point</artifactId>
<version>2.4.5</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-hotspot</artifactId>
<version>2.4.5</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-samples</artifactId>
<version>2.4.5</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-area</artifactId>
<version>1.1.6</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-point</artifactId>
<version>1.1.6</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-hotspot</artifactId>
<version>1.1.6</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-samples</artifactId>
<version>1.1.6</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-area</artifactId>
<version>1.0.13</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-point</artifactId>
<version>1.0.13</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-hotspot</artifactId>
<version>1.0.13</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-samples</artifactId>
<version>1.0.13</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-area</artifactId>
<version>1.0.6</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-point</artifactId>
<version>1.0.6</version>
</dependency><dependency>
<groupId>info.magnolia.dam</groupId>
<artifactId>magnolia-dam-focal-hotspot</artifactId>
<version>1.0.6</version>
</dependency><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 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/decorations/imaging/config.yamlgenerators:
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.yamlgenerators:
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:
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:
label: Focal Hotspot
form:
properties:
title:
label: Title
$type: textField
i18n: trueYou 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.
providers:
jcrProvider:
renderers:
imaging:
class: info.magnolia.dam.focal.renderer.FocalPointRendererAdditionally, 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:
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 You can disable a rendition by adding the property |
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 | ||
|---|---|---|---|
|
The context root.
|
||
|
The imaging servlet and the related generator.
|
||
|
The focal area imaging operation.
|
||
|
optional The focal area operation name.
|
||
|
The requested size
|
||
|
The JCR workspace.
|
||
|
The asset JCR id.
|
||
|
The 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 - Example
-
/magnolia/.imaging/focalpoint/Wide/1600x900/dam/jcr:aa26dabe-cdfc-4f4d-9f4a-6e1e1327806e/magazine.png
| Item | Description | ||
|---|---|---|---|
|
The context root.
|
||
|
The imaging servlet and the related generator.
|
||
|
The focal area imaging operation.
|
||
|
optional The focal point operation name.
|
||
|
The requested size
|
||
|
The JCR workspace.
|
||
|
The asset JCR id.
|
||
|
The asset name (SEO purpose).
|
|
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.
|
references:
- name: assetReference
propertyName: image
referenceResolver:
class: info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition
implementationClass: info.magnolia.dam.focal.rest.reference.AssetFocalReferenceResolverTemplating functions
The module provides 3 templating functions:
| You can find examples for each of them in the magnolia-dam-focal-samples project. |
Changelog
The Changelog covers all updates related to this module.
| Version | Notes | ||
|---|---|---|---|
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
Updated for Magnolia 6.0 compatibility. |
||
|
|||
|
|||
|
|||
|
|||
|
|||
|
Fixed bug when uploading new assets |
||
|
Initial release of the extensions version of the module.
|