Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.

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

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.

Installing

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

<dependency>
  <groupId>info.magnolia</groupId>
  <artifactId>magnolia-module-imaging</artifactId>
  <version>3.2.8</version>
</dependency>

Pre-built jars are also available for download. See Installing a module for help.

Image request processing

The diagram shows the elements of the Imaging module and how they interrelate (credit: Richard Unger).

  • ImagingServlet  is responsible for the actual generation of the images.
  • ImageGenerator interface is the entry point for generating images .
  • ImageOperationChain   implements ImageGenerator and executes an operation chain .
  • Various implementations of ParameterProviderFactory   interface are responsible for instantiating parameter providers for a given environment.
  • Implementations of ImageStreamer   interface are responsible for pushing the generated image, with the given generator and parameters, to an output stream.

Imaging servlet

ImagingServlet is registered in the Magnolia servlet filter chain in /server/filters/servlets/ImagingServlet. The servlet is responsible for generating images.

Node nameValue

 server


 filters


 context


 ...


 servlets


 log4j


 ...


 ImagingServlet


 mappings


 -.imaging--


 pattern

/.imaging/*

 parameters


  storeGeneratedImages

true

 class

info.magnolia.cms.filters.ServletDispatchingFilter

 comment

Imaging Servlet

 enabled

true

 servletClass

info.magnolia.imaging.ImagingServlet

 servletName

ImagingServlet

Image generators

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 nameValue

 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.

<generator name>

required

The name of the image generator.

large, portrait and thumbnail are used in the UI to generate images in apps. mte generates image variations in a theme.

class

required

The image generator class:

  • DefaultImageGenerator : Default image generator with provided OutputFormat and ImageOperation defaults.
  • ImageOperationChain : Image generator that delegates to a list of ImageOperation instances. This is the most commonly used generator class. It executes an operation chain and is used by largeportrait and thumbnail generators
  • ThemeAwareImageGenerator : Theme-aware generator that handles image variations in a theme. Extends ImageOperationChain.

outputFormat


required

Output format configuration.

parameterProviderFactory

required

Parameter provider factory class.

operations

required *for image operation chains

Image operations configuration.


Output format

The output format is the format or file type the generator produces, such as JPEG or PNG. Supported formats are bmpgifjpegjpgpng, 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 magnolia-module-imagingtools.jar The Image I/O plugins app displays a list of supported file extensions.

The output format is configured in /modules/imaging/generators/<generator name>/outputFormat.

Examples: Output format configurations.

Node nameValue

 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 jpg or png.

quality

required

Image quality as a percentage.

formatName

required *for ImageOperationChain only

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.

Parameter provider factory

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 nameValue

 generators


 mte


 outputFormat


 parameterProviderFactory


 class

info.magnolia.templating.imaging.parameters.ThemeAwareParameterProviderFactory

 class

info.magnolia.templating.imaging.ThemeAwareImageGenerator

Parameter provider classes:

info.magnolia.imaging.parameters.BinaryNodeIdentifierParameterProviderFactory

Node-based  ParameterProviderFactory  that tries to determine the  Node  by its identifier.

info.magnolia.imaging.parameters.BinaryNodePathParameterProviderFactory

Node-based  ParameterProviderFactory  that will tries to determine the  Node  by its path.

info.magnolia.templating.imaging.parameters.ThemeAwareParameterProviderFactory

Theme -aware ParameterProviderFactory .
info.magnolia.imaging.parameters.AbstractWorkspaceAndPathParameterProviderFactorySuperclass for parameter provider factories based on workspace and path.
info.magnolia.imaging.parameters.AbstractWorkspaceAndIdentifierParameterProviderFactoryExtracts 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.AbstractWorkspaceAndUuidParameterProviderFactoryExtracts 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.

Image operation chains

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 nameValue
 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.

operations

required

Operations node.

<operation names>

required

One node for each operation in the chain, for example load, resize and overlay. The chain is executed from top to bottom.

class

required

Operation class

<properties>

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.

ParameterProviderFactory and load operation class typing

Note that ParameterProviderFactory and ParameterProvider implementations are typed. Let's have a look at the interfaces:(warning) 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.

Creating a custom generator

You can create a custom image generator If the defaults do not meet your requirements:

  • Subclass ImageOperationChain.
  • Override getOutputFormat() method.
  • Set the value of the class node in configuration to your class' name.

Example operation chain: Image with watermark

Lets create a simple example of an operation change which produces an image with a watermark.

Node nameValue

 modules


 imaging


 config


 generators


 custom-generator-3


 class

info.magnolia.imaging.operations.ImageOperationChain

 parameterProviderFactory


 class

info.magnolia.imaging.parameters.BinaryNodePathParameterProviderFactory

 outputFormat


 formatName

jpg

 quality

80

 operations


 load


 class

info.magnolia.imaging.operations.load.FromBinaryNode

 resize


 class

info.magnolia.imaging.operations.cropresize.BoundedResize

 maxHeight

1024

 maxWidth

1024

 addText


 class

info.magnolia.imaging.operations.text.FixedText

 text

© by John Doe

 x

80

 y

80

 textStyle


 color

#FF3030

 fontName

Arial

 fontSize

40

 fontStyle

1

Registering a TextStyleTransformer

At the moment one must register a TextStyleTransformer in the module descriptor:

<components>
  <id>main</id>
  <component>
    <type>info.magnolia.imaging.operations.text.TextStyleTransformer</type>
    <implementation>info.magnolia.imaging.operations.text.TextStyleTransformer</implementation>
  </component>
</components>

And  TextStyleTransformer  doesn't work at the moment; see  MGNLIMG-180 - Getting issue details... STATUS .

Calling the image

Pattern: <context>/.imaging/<generator-name>/<jcr-workspace-name>/<path-to-binary-node>.<suffix-according-to-output-type>

http://localhost:8080/magnoliaAuthor/.imaging/custom-generator-2/dam/examples/jimi-hendrix.jpg/jcr:content.jpg

Imaging workspace

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

Viewing generated images

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

Caching

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 /server/filters/servlets/ImagingServlet/parameters, create a new property storeGeneratedImages, and set the value to false.

Node nameValue

 server


 filters


 servlets


 ImagingServlet


 parameters


 storeGeneratedImages

false

(warning) 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

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.

Image variations in 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.

Configuring an image operation in a variation

/modules/site/config/themes/travel-demo-theme/imaging/variations

Node nameValue

 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: