DAM templating

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.

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:

Add a content node damfn.
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 name	Value
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

Method	Description	Return
`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 method	2.x method	Return
`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

Method	Conversion	Return
`ItemKey getItemKey()`	`new ItemKey(oldApiAsset.getAssetProviderIdentifier(), oldApiAsset.getIdentifier())`	ItemKey
`String getFileName()`	`oldApiAsset.getFileName() + '.' + oldApiAsset.getFileExtension()`	FileName
`getLink()`	`oldApiAsset.getLink()`	Link
`isFolder()`	`false`	Boolean
`isAsset()`	`true`	Boolean
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

Method	Description	Return
`getCreated()`	Returns null	Calendar
`<M extends AssetMetadata> M getMetadata(Class<M> metaDataType)`	Throws `UnsupportedOperationException`	AssetMetaData
`getParent()`	Throws `UnsupportedOperationException`	Folder
`getAssetProvider()`	Throws `UnsupportedOperationException`	AssetProvider

Page tree