Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
The Imaging module simplifies working with images. You don't need to resize and crop each image by hand as the imaging engine generate variations on-the-fly. Administrators create the rules that determine the sizes of derivatives. Editors save time as they can select an image from the DAM or upload one, and it will be automatically adapted to match the rule.
groupId
and artifactId
) have changed since Magnolia 5.5.If you have custom Java code relying on this module, you need to install a compatibility module too.
To be sure - please check the module on our Bitbucket server.
Note the changes in groupId
and artifactId
since the 3.4 release.
With Magnolia 5.6 we've begun removing the old Content API from our modules. If you have custom code relying on classes from the old imaging module then you must do one of two things:
magnolia-imaging-compatibility
module together with the magnolia-core-compatibility
module.The diagram shows the elements of the Imaging module and how they interrelate (credit: Richard Unger).
ImageGenerator
and executes an operation chain .
ImagingServletis registered in the Magnolia servlet filter chain in /server/filters/servlets/ImagingServlet
. The servlet is responsible for generating images.
Node name | Value |
---|---|
server | |
filters | |
context | |
... | |
servlets | |
log4j | |
... | |
ImagingServlet | |
mappings | |
-.imaging-- | |
pattern | /.imaging/* |
parameters | |
class | info.magnolia.cms.filters.ServletDispatchingFilter |
comment | Imaging Servlet |
enabled | true |
servletClass | info.magnolia.imaging.ImagingServlet |
servletName | ImagingServlet |
ImageGenerator is a component that generates variants from a source image based on configuration. Generators are used by image provider classes to render images in the UI and on pages.
Generators are configured in /modules/imaging/config/generators
.
Example: Generator configurations:
Node name | Value |
---|---|
modules | |
imaging | |
config | |
generators | |
default | |
large | |
outputFormat | |
operations | |
parameterProviderFactory | |
class | info.magnolia.imaging.operations.ImageOperationChain |
portrait | |
thumbnail | |
mte | |
outputFormat | |
parameterProviderFactory | |
class | info.magnolia.templating.imaging.ThemeAwareImageGenerator |
Properties:
generators | required Generators configuration. |
| required The name of the image generator.
|
| required The image generator class:
|
| required Output format configuration. |
| required See the Parameter provider factory class. |
| required *for image operation chains See the Image operation chains configuration. |
The output format is the format or file type the generator produces, such as JPEG or PNG. Supported formats are bmp
, gif
, jpeg
, jpg
, png
, and wbmp
. The module also supports these formats and tiff
as input formats . You can verify the available formats on your system by installing the
The output format is configured in /modules/imaging/generators/<generator name>/outputFormat
.
Examples: Output format configurations.
Node name | Value |
---|---|
generators | |
large | |
outputFormat | |
formatName | jpg |
quality | 80 |
operations | |
parameterProviderFactory | |
class | info.magnolia.imaging.operations.ImageOperationChain |
mte | |
outputFormat | |
quality | 80 |
parameterProviderFactory | |
class | info.magnolia.templating.imaging.ThemeAwareImageGenerator |
Properties:
outputFormat | required Output format configuration. Defines the format the generator produces, such as |
| required Image quality as a percentage. |
| required *for The file extension of the generated images. |
ThemeAwareImageGenerator
generates images in the same format as the source image. If you upload a jpg
, this generator will produce a jpg
.
Parameters are instructions passed to an operation, such as where to load a source image or what text to lay over it. Registering a ParameterProviderFactory allows you to pass parameters from different sources:
The parameter provider factory is configured in /modules/imaging/generators/<generator name>/parameterProviderFactory
.
Node name | Value |
---|---|
generators | |
mte | |
outputFormat | |
parameterProviderFactory | |
class | info.magnolia.templating.imaging.parameters.ThemeAwareParameterProviderFactory |
class | info.magnolia.templating.imaging.ThemeAwareImageGenerator |
Parameter provider classes:
| Node-based ParameterProviderFactory that tries to determine the Node by its identifier. |
| Node-based ParameterProviderFactory that will tries to determine the Node by its path. |
| Theme -aware ParameterProviderFactory . |
info.magnolia.imaging.parameters.AbstractWorkspaceAndPathParameterProviderFactory | Superclass for parameter provider factories based on workspace and path. |
info.magnolia.imaging.parameters.AbstractWorkspaceAndIdentifierParameterProviderFactory | Extracts workspace and identifier from the path. Everything after the identifier is ignored. This allows you, for example, to pass a properly named file name, to the image. |
info.magnolia.imaging.parameters.AbstractWorkspaceAndUuidParameterProviderFactory | Extracts workspace and UUID from the path. Everything after the UUID is ignored. This allows you, for example to pass a properly named file name to the image. |
The Imaging module can resize and crop images, overlay text and apply image filters. These are called image operations and are configured in /modules/imaging/config/generators/<generator name>/operations
. Image operations can also be configured in a theme.
An image operation chain consists of one or more operations. A simple chain could add only fixed text, while a more complex chain could load an image from a remote source, apply filters, add multiple text fields and style them differently.
Example: Image operation chain configuration:
Node name | Value |
---|---|
modules | |
imaging | |
config | |
generators | |
myOperationChain | |
operations | |
load | |
class | info.magnolia.imaging.operations.load.FromBinaryNode |
resize | |
class | info.magnolia.imaging.operations.cropresize.BoundedResize |
maxHeight | 600 |
maxWidth | 600 |
overlay | |
outputFormat | |
parameterProviderFactory | |
class | info.magnolia.imaging.parameters.BinaryNodePathParameterProviderFactory |
class | info.magnolia.imaging.operations.ImageOperationChain |
Properties
<generator name> | required Name of the image generator. |
| required Operations node. |
| required One node for each operation in the chain, for example |
| required Operation class |
| required/optional Other properties supported by the operation class. |
The first operation in an operation chain is typically a load operation. Use load class FromBinaryNode to load an image from the DAM.
Note that ParameterProviderFactory and ParameterProvider implementations are typed. Let's have a look at the interfaces: Return type of
ParameterProviderFactory#newParameterProviderFor
and the method argument in the class used for a load operation must have the same type!
For instance BinaryNodePathParameterProviderFactory (as ParameterProviderFactory) and FromBinaryNode work nicely together.
You can create a custom image generator If the defaults do not meet your requirements:
ImageOperationChain
.getOutputFormat()
method.class
node in configuration to your class' name.The imaging engine stores generated images in the imaging
workspace.
The path where generated images are stored depends on the CachingStrategy. The default path is:
/<generatorName> /<workspaceName> /<path of node or property (nodedata)>
For the MTE generator, the path is:
/mte /<themeName> /<variationName> /<path of node or property (nodedata)>
For example:
/mte /travel-demo-theme /960 /dam /tours /shark_brian_warrick_0824.JPG /jcr:content /generated image
When the image is rendered on a page, the URL to the generated image is:
/<CATALINA_HOME, contextPath> /.imaging (which is the Imaging servlet default path) /<generatorName> /<path to the cached image>
Here's the same image generated by the portrait
and mte
generators in the JCR Browser app. The 960
variation is configured in the travel-demo-theme
.
The syntax for the URL to request a generated image depends on the used ParameterProviderFactory. However, it usually has the following pattern:
<protocol>://<context>/.imaging/<generator name>/<specific parameters ...>
Here is an example of a path when using BinaryNodePathParameterProviderFactory:
<protocol>:<context>/.imaging/<generator-name>/<jcr-workspace-name>/<path-to-binary-node>.<suffix-according-to-output-type>
Example: http://localhost:8080/magnoliaAuthor/.imaging/custom-generator-2/dam/examples/jimi-hendrix.jpg/jcr:content.jpg
Magnolia caches image resources to improve performance. Any dynamic images generated by the Imaging module are cached at two levels: in the imaging
workspace and in the actual cache like any other page or document. This means that once the system generates an image, you keep getting the same cached image on subsequent requests.
During testing, you can disable caching of generated images completely. In /modules/imaging/config
, create a new property storeGeneratedImages
, and set the value to false
.
Node name | Value |
---|---|
modules | |
imaging | |
config | |
storeGeneratedImages | false |
There is still a small delay between configuration changes and a new image being available. Magnolia's observation mechanism intentionally waits couple of seconds before reading a changed configuration.
Imaging support is enabled by 3 Magnolia modules:
magnolia-imaging-support | ImagingSupport | The support interface for imaging. |
magnolia-dam-imaging | ImagingBasedAssetRenderer | Asset renderer that uses ImagingSupport to generate renditions. |
magnolia-templating-essentials-imaging | ThemeDelegatingImagingSupport | ImagingSupport that delegates to a Theme. |
A variation is an theme-specific configuration that defines the size of the target image and tells the imaging engine whether cropping is allowed. Variations are configured in a theme which allows you to configure image look and feel in the same place as CSS.
See Image variations and Displaying resized images for more.
/modules/site/config/themes/travel-demo-theme/imaging/variations
Node name | Value |
---|---|
site | |
config | |
themes | |
travel-demo-theme | |
imaging | |
variations | |
operation-chain | |
outputFormat | |
formatName | jpg |
quality | 80 |
operations | |
load | |
class | info.magnolia.imaging.operations.load.FromBinaryNode |
resize | |
class | info.magnolia.imaging.operations.cropresize.BoundedResize |
maxHeight | 500 |
maxWidth | 500 |
class | info.magnolia.imaging.operations.ImageOperationChain |
parameterProviderFactory | |
class | info.magnolia.imaging.parameters.BinaryNodeParameterProviderFactory |
class | info.magnolia.templating.imaging.variation.ImageOperationProvidingVariation |
1600 | |
... | |
class | info.magnolia.templating.imaging.VariationAwareImagingSupport |
Credits:
4 Comments
Guillermo Ortiz Figueroa
It seems the maven definition is wrong. It should be:
Richard Gange
Hi. Yes, thanks for your comment. Several modules went through an update/refactoring. Today I am updating this page.
Tom Wespi
It seems that this documentation is outdated. Tried to use variations with 5.6.3, class "info.magnolia.templating.imaging.VariationAwareImagingSupport" does not exist anymore. Also in demoauthor, the imaging is completely different configured than in the examples above.
Richard Gange
You're right it could use some updating. The VariationAwareImagingSupport can be found in the MTE module. I believe at one time there were two different versions of the class or something. See VariationAwareImagingSupport docs here.