Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

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

This page is about Magnolia 5.2.x+ / DAM 2.0+ The way assets are registered and used changed. If you work with Magnolia 5.2+ or earlier, see  DAM templating 1.x.

In Magnolia 5.3 / DAM 2.0 DamTemplatingFunctions was moved to it's own DAM submodule. The new fully-qualified class name is info.magnolia.dam.templating.functions.DamTemplatingFunctions. All of the exposed utility methods are still supported, but most are deprecated.

The DAM Templating module provides one main utility class,  DamTemplatingFunctions , for use in templates and model classes. This class provides direct access to Assets, Folders, Maps and AssetRenditions and defines useful methods. Templating functions are exposed in Freemarker templates as damfn.

Injecting templating functions

DamTemplatingFunction can be injected into any model class.

@Inject
public CustomFunction(DamTemplatingFunctions damTemplatingFunction) {
    this.damTemplatingFunction = damTemplatingFunction;
}
public Asset getAsset(String itemKey) {
    return this.damTemplatingFunctions.getAsset(itemKey);
}

Using methods in templates

Methods provided by DamTemplatingFunctions are exposed in Freemarker templates using damfn in the same way as cmsfn and stkfn are used. For example:
[#assign asset = damfn.getAssetForId(content.identifier)]
[#assign assetMap = damfn.getAssetMap(asset)]

getAssetMap(Asset asset):Map<String,String> provides access to Asset and metadata properties using DamTemplatingFunctions. For example:

[#assign assetMap = damfn.getAssetMap(asset)]
<br>assetMap.title = ${assetMap.title}
<br>assetMap.metadata.dc.title = ${assetMap.metadata.dc.title}

Configuring a custom renderer

DamTemplatingFunctions are available in the STK. The renderer configuration is in /modules/standard-templating-kit/renderer/contextAttributes/stk/damfn. See  DAM and the STK for more information.

If your module is not dependent on the STK, extend your renderer configuration to include DamTemplatingFunctions.

(warning) Your module needs to depend on the magnolia-dam-templating module. See Module dependencies for more.

To configure a custom renderer, in /modules/<module name>/renderers/<renderer name>/contextAttributes:

  1. Add a content node damfn.
  2. Add two properties :
    1. componentClass and set the value to info.magnolia.dam.templating.functions.DamTemplatingFunctions.
    2. name and set the value to damfn.
Node nameValue

 my-module

 

 renderers

 

 customRenderer

 

 contextAttributes

 

 cms

 

 cmsfn

 

 damfn

 

 componentClass

info.magnolia.dam.templating.functions.DamTemplatingFunctions

 name

damfn

 class

info.magnolia.module.myModule.renderers.CustomRenderer

Main methods in 2.x

MethodDescriptionReturn
getAsset(String itemKey)
  • Retrieves an Asset based on an itemKey.
  • Deleted or hidden Assets are not returned.
Asset
getAsset(String providerId, String assetPath)
  • Retrieves an Asset based on a providerId and assetPath.
  • Deleted or hidden Assets are not returned.
  • For JCR Assets the assetPath is an absolute JCR path, for example /demo-project/images/assetImage1.
  • Throws IllegalArgumentException if the requested provider is not an implementation of PathAwareAssetProvider.
Asset
getAssetForAbsolutePath(String providerId, String absoluteAssetPath)
  • Retrieves an Asset based on a providerId and AbsoluteAssetPath.
  • Deleted or hidden Assets are not returned.
  • Throws IllegalArgumentException if the requested provider is not an implementation of PathAwareAssetProvider.
Asset
getAssetLink(info.magnolia.dam.api.Asset asset, com.google.common.net.MediaType mediaType, String renditionName)
  • Returns AssetRendition.getLink()based on the passed mediaType and  renditionName.
  • Returns null in case of exception or if Asset or AssetRendition are not found.
String
getAssetLink(String assetKey)
  • Returns the link to the specified Asset for a given assetKey.
  • Returns null in the case of an exception or if Asset is not found.
String
getAssetLink(String itemKey, String renditionName)
  • Returns the link to the specified Asset for a given itemKey and renditionName.
  • Returns null in the case of an exception or if Asset or AssetRendition are not found.
String
getAssetMap(info.magnolia.dam.api.Asset asset)
  •  Creates a read only map containing:
    •   All asset property names and values
    •   A metadata child map containing all supported metadata property names and values.
Map
getAssetMap(String itemKey)
  • Creates a read only map corresponding to the itemKey.
  • Returns null in the case of an exception or if Asset is not found.
Map
getAssetMapForAssetId(String assetKey)
  • Creates a read only map corresponding to the assetKey.
  • Returns null in the case of an exception or if Asset is not found.
Map
getFolder(String itemKey)
  • Retrieves a Folder based on an itemKey.
  • Deleted or hidden Folders are not returned.
Folder
getFolder(String providerId, String folderPath)
  • Retrieves a Folder based on a providerId and folderPath.
  • Deleted or hidden Folders are not returned.
  • Throws IllegalArgumentException if the requested provider is not an implementation of PathAwareAssetProvider.
Folder
getItems(String providerId, info.magnolia.dam.api.AssetQuery assetQuery)
  • Returns Items based on an assetQuery for a specified providerId.
  • Set AssetQuery.includesFolders() or AssetQuery.includesAssets() to restrict the returned Items.
Iterator
getRendition(info.magnolia.dam.api.Asset asset, com.google.common.net.MediaType mediaType, String renditionName)
  • Returns an appropriate AssetRenderer based on the passed MediaType and Asset.
  • From the AssetRenderer returns the AssetRendition for the given renditionName.
AssetRendition
getRendition(info.magnolia.dam.api.Asset asset, String renditionName)
  • Retrieves an AssetRendition based on the MediaType built from the Asset.getMimeType().
AssetRendition
getRendition(String itemKey, com.google.common.net.MediaType mediaType, String renditionName)
  • Retrieves an AssetRendition based on the itemKey for a given MediaType.
AssetRendition
getRendition(String itemKey, String renditionName)
  • Retrieves an AssetRendition based on the itemKey for a given renditionName.
AssetRendition
provides(String providerId, com.google.common.net.MediaType mediaType)
  • Returns AssetProvider.provides(MediaType)or false in case of any exceptions.
Boolean

Deprecated in 2.x

1.x method2.x methodReturn
getAssetForId(String assetIdentifier)getAsset(String)Asset
getAssetForPath(String assetPath)getAssetForAbsolutePath(String, String)Asset
getAssetLinkForId(String assetKey)getAssetLink(String)String
getAssetLinkForId(String itemKey, String renditionName)getAssetLink(String, String)String
getAssetRendition(info.magnolia.dam.api.Asset asset, String renditionName) getRendition(Asset, MediaType, String)Asset
getAssetRenditionForAssetId(String itemKey, String renditionName)getRendition(String, MediaType, String)Asset
getAssetsForFilter(info.magnolia.dam.api.AssetQuery assetQuery)getItems(String, AssetQuery)List
getAssetsFromFolderId(String folderKey)getFolder(String) and the Folder.getChildren()List

OldToNewAsset implements the DAM 2.x Asset API by wrapping an instance of the 1.x Asset. This class is included in the DAM compatibility module and contains a list of methods of the old API that can and cannot be implemented in DAM 2.x.

1.x methods that can be implemented in 2.x

MethodConversionReturn
ItemKey getItemKey()new ItemKey(oldApiAsset.getAssetProviderIdentifier(), oldApiAsset.getIdentifier())ItemKey
String getFileName()oldApiAsset.getFileName() + '.' + oldApiAsset.getFileExtension()FileName
getLink()oldApiAsset.getLink()Link
isFolder()falseBoolean
isAsset()trueBoolean
Plain delegate methods  

getName()

oldApiAsset.getName()String

getLanguage()

oldApiAsset.getLanguage()String
getComment()oldApiAsset.getComment()String
getTitle()oldApiAsset.getTitle()String
getSubject()oldApiAsset.getSubject()String
getDescription()oldApiAsset.getDescription()String
getCaption()oldApiAsset.getCaption()String
getCopyright()oldApiAsset.getCopyright()String
getMimeType() oldApiAsset.getMimeType()String
getFileSize()oldApiAsset.getFileSize()Long
getContentStream()return oldApiAsset.getContentStream()InputStream
getPath()oldApiAsset.getPath()String
getLastModified()oldApiAsset.getLastModified()Calendar

1.x methods that cannot be implemented in 2.x

MethodDescriptionReturn
getCreated()Returns nullCalendar
<M extends AssetMetadata> M getMetadata(Class<M> metaDataType)Throws UnsupportedOperationExceptionAssetMetaData
getParent()Throws UnsupportedOperationExceptionFolder
getAssetProvider()Throws UnsupportedOperationExceptionAssetProvider