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 1.x. The way assets are registered and used changed. If you work with Magnolia 5.3+ see DAM templating.

DAM utility classes

The Dam API 1.x provides two main utility classes:

  • DamTemplatingFunctions for use in templates and model classes. This class provides direct access to Assets and defines useful methods.
  • AssetMap for use in templates to directly call Asset properties with notations such as asset.<propertyName>.

Injecting templating functions

DamTemplatingFunction can be injected into any model class.

@Inject
public CustomFunction(DamTemplatingFunctions damTemplatingFunction) {
    this.damTemplatingFunction = damTemplatingFunction;
}
public Asset getAsset(String assetIdentifier) {
    return this.damTemplatingFunction.getAssetRenditionForAssetId(assetIdentifier, "renditionName");
}

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.link)]
[#assign assetMap = damfn.getAssetMapForAssetId(content.link)]

AssetMap provides access to Asset and metadata properties using DamTemplatingFunctions. For example:

[#assign assetMap = damfn.getAssetMapForAssetId(content.link)]    
 
<br>assetMap.title = ${assetMap.title}
<br>assetMap.metadata.dc.title = ${assetMap.metadata.dc.title}

Configuring a custom renderer

DamTemplatingFunctions are available in the STK. You can find the renderer configuration at Configuration > /modules/standard-templating-kit/renderer/contextAttributes/stk/damfn. See DAM 1.x and the STK for more information.

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

(warning) Note that your module needs to depend on the dam module. See Module dependencies form more information.

In Configuration > /modules/<module name>/renderers/<renderer name>/contextAttributes:

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

 my-module

 

 renderers

 

 customRenderer

 

 contextAttributes

 

 cms

 

 cmsfn

 

 damfn

 

 componentClass

info.magnolia.dam.asset.functions.DamTemplatingFunctions

 name

damfn

 class

info.magnolia.module.myModule.renderers.CustomRenderer

Accessing custom properties

Consider the following scenario:

  • You extend the DAM API 1.x to include two additional custom metadata properties: longComment and reviewer.
  • New Assets now include these two additional properties that are added to the JCR Asset node as properties, provided their values are not empty.

You have two options to access the custom properties:

  • In templates using AssetMap.longComment.
  • In model classes using Asset.getCustomProperty(String propertyName):Object
    private DamManager damManager;
    // BY Injection
    @Inject
    public CustomFunction(DamManager damManager) {
        this.damManager = damManager;
    }
    
    public Object myCustomProperty(String assetId, String customPropertyName) {
        Asset asset = damManager.getAssetForId(assetId);
        return asset.getCustomProperty(customPropertyName);
    }

Main methods

Here are the main methods exposed by the DAM API and how you can use them in your templates.

DamManager

MethodDescriptionReturn
getAssetForId(String assetIdentifier)

  • Retrieves an Asset based on an assetIdentifier.
  • Deleted or hidden Assets are not returned.
  • For JCR Assets the assetIdentifier is a composite key, for example jcr:178effda-d054-4a5a-a8f0-f0546754484e
Asset
getAssetForPath(String assetPath)

 

  • Retrieves an Asset based on an Asset path.
  • Deleted or hidden Assets are not returned.
  • Logic:
    • Iterate the registered provider.
    • For every active provider call AssetProvider.getAssetIdentifierForPath(String assetPath)and keep the result if not null.
      • If one and only one result is found, return the related Asset.
      • If no results or more than one result is found, log and return null.
  • For JCR Assets the assetPath is an absolute JCR path, for example /demo-project/images/assetImage1
Asset
getAssetsFromFolderId(String folderIdentifier)

  • Retrieves an Asset list based on a folder identifier.
  • Like the assetIdentifier, the folder identifier is a composite key, for example jcr:178effda-d054-4a5a-a8f0-f0546754484e.
  • Deleted or hidden Assets are not returned.
List<Asset>
getAssetsForFilter(AssetFilter assetFilter)

  • Retrieves an Asset list based on an Asset filter.
  • This implementation supports multi-asset types, i.e.assets linked to different providers.
  • Logic:
  • Iterate the registered provider.
    • For every active provider call AssetProvider.getAssetsForFilter(AssetFilter assetFilter).
    • Concatenate the results.
  • Current Asset filter properties:
    • folderPath: /demo-project/img/bk/Opener/% for example, will only return assets found under this folder. 
    • extension: jpg for example, will only return Assets with the specified extension.
List<Asset>
getAssetMap(Asset asset)Returns the AssetMap representation of the AssetAssetMap is mainly used in templates to simplify data access.AssetMap

DamTemplatingFunctions

MethodDescriptionReturn

getAssetsFromFolderId(String folderIdentifier)

  • Retrieves an Asset list based on a folder identifier.
  • Like the assetIdentifier, the folder identifier is a composite key, for example jcr:178sidi-d054-d8f8-f4568557d.
  • Deleted or hidden Assets are not returned.
List<Asset>
getAssetMap(Asset asset)
  • Returns the AssetMap representation of the Asset.
  • AssetMap is mainly used in templates to simplify data access.
AssetMap
getAssetMapForAssetId(String assetIdentifier)
  • Returns the AssetMap representation of the Asset identified by the requested assetIdentifier.
  • AssetMap is mainly used in templates to simplify data access.
AssetMap
getAssetForPath(String assetPath)
  • Retrieves an Asset based on an Asset path.
  • Deleted or hidden Assets are not returned.
Asset
getAssetForId(String assetIdentifier)
  • Retrieve an Asset based on an assetIdentifier.
  • Deleted or hidden Assets are not returned.
Asset
getAssetRendition(Asset asset, String renditionName)
  • Returns the specified AssetRendition for the passed Asset.
  • Where no Rendition is found, returns the same Asset.
  • Returns null in the case the of an exception.
Asset
getAssetRenditionForAssetId(String assetIdentifier, String renditionName)
  • Returns the specified AssetRendition based on the assetIdentifier.
  • Where no Rendition is found, returns the same Asset.
  • Returns null in the case of an exception or if assetIdentifier is null or blank.
(warning) This is the equivalent of STKTemplatingFunctions.getAssetVariation(... in Magnolia 4.5.
Asset

getAssetLinkForId(String assetIdentifier)

  • Returns the link to the specified Asset for a given assetIdentifier.
  • Returns null in the case of an exception or if Asset is not found.
String

getAssetLinkForId(String assetIdentifier, String renditionName)

  • Returns the link to the specified AssetRendition for a given assetIdentifier.
  • Returns null in the case of an exception or if Asset or AssetRendition is not found.
String