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 a Magnolia bundle, the required and optional modules are already included.
If you created a custom webapp, 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.
artifactId | version |
---|---|
|
3.0.5 |
|
3.4.4 |
Optional modules
Modules required when using a Rendition of an asset, such as size variations of an image. Recommended.
artifactId | version |
---|---|
|
1.4.1 |
|
1.5.3 |
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
Best practice
If you need different sizes of the same image, do NOT upload multiple copies (variations) of the same image to your DAM repository. Instead, upload the image only once and define image size variations in your theme.
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.
Theme variations configuration
Property | Description |
---|---|
|
optional Image variations for the various renditions of an image on the page. |
|
required VariationAwareImagingSupport provides support for variations. |
|
optional Enables and disables variation support. |
|
required Map of image variations. |
|
required The name of the variation, a.k.a the rendition name. Choose a name that describes the variation. The name is used in template scripts to reference the variation. Add one node for every variation. |
|
required You can use one of the available classes or create a custom one. The available properties depend on the class used for the variation. Any custom class must implement Variation. Magnolia Templating Essentials module provides:
|
|
Add properties that are supported by the class used. |
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
:
Property | Description | ||
---|---|---|---|
|
required Class must implement SimpleResizeVariation. |
||
|
optional* An integer to define the height in pixels. You must configure either height or width or both. |
||
|
optional* An integer to define the width in pixels. You must configure either height or width or both. |
||
|
optional, default is Defines whether cropping the image is allowed to fit the desired aspect ratio. Example: A source image in the DAM is 800x800 px (square). In a
variation you define the desired target size as 200x100 (rectangle) so
the aspect ratio changes. By default 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.
|
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.