How to work with images using damfn

This page explains how to work with images and other assets stored in the Magnolia Digital asset management using damfn templating functions in template scripts.

Imaging modules

If you use the Magnolia CE or EE bundles, the required and optional modules are already included.

If you created a custom bundle, add the following modules in the pom file of the webapp of your bundle. The modules may have dependencies to other modules but these dependencies are handled by Maven dependency management.

Required modules

Modules required for basic image operations.

Optional modules

Modules required when using a  Rendition  of an asset, such as size variations of an image. Recommended.

Selecting the image in dialog with a link field

To select an image in a dialog use the Link field, it stores a reference to the selected asset.

Example - code fragment from a dialog definition

form:
  tabs:
    - name: tabImage
      fields:
        - name: image
          class: info.magnolia.ui.form.field.definition.LinkFieldDefinition
          targetWorkspace: dam
          appName: assets
          identifierToPathConverter:
            class: info.magnolia.dam.app.assets.field.translator.AssetCompositeIdKeyTranslator
          contentPreviewDefinition:
            contentPreviewClass: info.magnolia.dam.app.ui.field.DamFilePreviewComponent

Displaying an image

To render an image, you need to get a link to the asset. Use the link as a value in the src attribute of the img element.

Getting an image link with an itemKey

Use the #getAssetLink(itemKey) method if you have the itemKey of the image. See: Get link for asset. For instance, the textImage component stores the itemKey in the image property. This is a very common use case.

Example: Getting an image link with an itemKey. Assume that this code is executed in a component template. The current content node has a property named image where the itemKey is stored.

[#assign imgItemKey = content.image!]
[#if imgItemKey??]
    [#assign imgRef = damfn.getAssetLink(imgItemKey)!]
    [#if imgRef??]
        <img src="${imgRef}"/>
    [/#if]
[/#if]

Getting an image link for an asset

Use the #getLink() method if you already have the asset. Since an  Asset  object is a Java bean you can use its public method #getLink(). You may even use the dot notation.

Example: Getting an image link for an asset

[#assign myAsset = damfn.getAsset("jcr","/photos/pool.jpg")!]
[#if myAsset??]
    <img src="${myAsset.getLink()}"/>
[/#if]
 
[#assign myAsset = damfn.getAsset("jcr","/photos/dilbert.jpg")!]
[#if myAsset??]
    <img src="${myAsset.link}"/>
[/#if]

Displaying resized images

Defining image variations

Configure your image variations in a theme. Each variation should be a node under <my-theme>/imaging/variations. The variation node name such as small-square is what you will be referencing in your template scripts. It is also known as rendition name.

Example: Defining three image variations in a theme.

On the node /modules/site/config/themes/<your-theme>/imaging you must specify the class property. The used class must implement ImagingSupport. MTE module provides VariationAwareImagingSupport which is a good choice for our use case here. 

Add one node for every required variations below <your-theme>/imaging/variations. The name of such a node is the name of the variation. also known as the rendition name. In the example above we have defined the renditions small-square, thumbnail and medium. 

For every variation you have to configure some properties. The available properties depend on the class you use in the variation. You can implement your own class. The definition class must implement the Variation interface.

In the example above we use SimpleResizeVariation. This class is provided by the magnolia-templating-essentials-imaging module. Your webapp bundle must contain the module.

Properties of SimpleResizeVariation:

 *) You must define either width or height. If you do not define either, the renderer internally throws an ImagingException but displays the default size, the size of the original uploaded image. When you define both width and height, the image is resized accordingly and is cropped if the ratio does not fit. If you define only width or only height, the other property is calculated accordingly based on the ratio of the original image.

 Make sure the site where you want to display the image variations references the theme. In the Site app, the theme name property must be the same as the main node of the configured theme, in this example my-theme.

Getting an image variation

Example: Getting an image variation (asset rendition) with an itemKey. Assume that content in this example stores the itemKey in the image property.

[#assign imgItemKey = content.image!]
[#if imgItemKey??]
    [#assign myMediumRendition = damfn.getRendition(imgItemKey, "medium")!]
    [#if myMediumRendition??]
        <img src="${myMediumRendition.getLink()}"/>
    [/#if]
[/#if]

Example: Getting an image variation (asset rendition) for an asset.

[#if myAsset?? && myAsset.isAsset()]
    [#assign myThumbnail = damfn.getRendition(myAsset, "thumbnail")!]
    [#if myThumbnail??]
        <img src="${myThumbnail.getLink()}"/>
    [/#if]
[/#if]

Image variation cache

Magnolia caches image resources to improve performance. Any dynamic images generated by the Imaging module are also 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.

Disable image cache during development

During developing it is helpful to disable caching of generated images completely. Go to Configuration > /server/filters/servlets/ImagingServlet/parameters, create a new property storeGeneratedImages, and set its value to false.

 Remove the property or to set it to true after having finished image variation development. Do not use this property in your production environment!

Deleting imaging variations in the imaging workspace

Once image variations are stored in the imaging workspaces, they remain there. After you remove the storeGeneratedImages property, any cached image variations are served from the imaging workspace again. Delete the nodes from the workspace.

Option 1: Groovy script. In the script, examples-theme is the name of your theme. You can run this script in the Groovy console or add a new script and run it.

session = MgnlContext.getJCRSession('imaging')
images = session.getNode('/examples-theme')
images.remove()
session.save()

Option 2: Delete the nodes in the imaging workspace in JCR Browser app.