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.3+ / DAM 2.0+. The way assets are registered and used changed. If you work with Magnolia 5.2.x or earlier, see  DAM 1.x and the STK.

The DAM API is fully integrated with Standard Templating Kit (STK).

DAM STK interaction

Using the stkTextImage component as an example, we demonstrate below how the STK interacts with the DAM API. Images in components are backed by Assets.

Here's what happens when the STK renders a simple image

  • The TextImageModel is called by the textImage.ftl script. The component queries the DAM API for an asset.
    • The query argument is the ItemKey that is stored in the image property of the component. The ItemKey for the default JcrAssetProvider is a composite id, for example jcr:178effda-d054-4a5a-a8f0-f0546754484e.
    • TextImageModel has access to DamTemplatingFunctions by injection in the model class. The provided methods are bound to a AssetProviderRegistry implemented class that acts as a dispatcher for assets.
  • DamTemplatingFunctions retrieves the original Asset.
    • AssetProviderRegistry defines the appropriate AssetProvider to use. The provider is referenced in the first part of the composite id.
    • AssetProvider assembles the Asset based on the specified storage location. Direct access to the binary media data is provided. This is typically from the internal asset node but could potentially come from an external source.
    • Asset is returned to DamTemplatingFunctions.
  • To ensure compatibility with previous template implementations, the returned Asset is wrapped in a STKAssetWrapper

When rendering a specific AssetRendition of an Asset

  • DamTemplatingFunctions.getRendition(String itemKey, String renditionName) first gets the original Asset
  • Based on this Asset, it's MediaType, and the registered  AssetRenderer, the AssetProviderRegistry retrieves the best-matching AssetRenderer.
  • An AssetRendition is then created based on the returned AssetRenderer.render(Asset asset, MediaType mediaType, String renditionName) call. 
  • STK registers its' own AssetRenderer called STKAssetRenderer.

The following diagram demonstrates the sequence call:

  1. DamTemplatingFunctions gets the related Asset from the registered AssetProvider.
  2. AssetProviderRegistry tries to resolve the registered AssetRenderer based on the Asset and its related MediaType. In our case this is a STKAssetRenderer
  3. STKAssetRenderer initializes an STKAssetRendition that creates a new Asset that represents the required rendition.
    (warning) STKAssetRenditiongetLink() uses the Imaging module to create the returned link.
  4. In order to stay compatible with previous implementations of FTL's, the returned Asset is wrapped into a STKAssetWrapper that exposes additional properties.

STKAssetRenderer configuration

The STK defines its own renderer,  STKAssetRenderer . Here's the configuration in /modules/dam/config//renderers/stkJcrRenderer.

Node nameValue

 modules

 

 dam

 

 config

 

 renderers

 

 stkJcrRenderer

 

 class

info.magnolia.module.templatingkit.dam.STKAssetRenderer

Using assets in model classes

To get an Asset from any model class or other business logic class add the following code to the class.

    // Get the DamTemplatingFunctions
    private DamTemplatingFunctions damTemplatingFunction;
    // Or based on your need
	// Get the AssetProviderRegistry
    private AssetProviderRegistry providerRegistry;
	
    // BY Injection
    @Inject
    public CustomFunction(AssetProviderRegistry providerRegistry, DamTemplatingFunctions damTemplatingFunction) {
        this.providerRegistry = providerRegistry;
		this.damTemplatingFunction = damTemplatingFunction;
	 }
    // OR by using Components
    public void myCustomMethod() {
        this.providerRegistry = Components.getComponent(AssetProviderRegistry.class);
		this.damTemplatingFunction = Components.getComponent(DamTemplatingFunctions.class);
	 }

    public Asset getAsset() {
		String itemKey = PropertyUtil.getString(content, getImageName());
		if(ItemKey.isValid(itemKey)) {
			ItemKey key = ItemKey.from(itemKey);
			return  this.providerRegistry.getProviderFor(key).getAsset(key);
		}
  		return null;
    }

    public Map<String, Object> getAssetMap() {
		String itemKey = PropertyUtil.getString(content, getImageName());
		if(ItemKey.isValid(itemKey)) {
			this.damTemplatingFunction.getAssetMap(itemKey);
		}
  		return null;
    }

Using assets in Freemarker scripts

Here are some examples you can use in your scripts. See Main methods for more examples.

[#assign assetMap = damfn.getAssetMapForAssetId(content.link)]    
[#assign asset = damfn.getAssetForId(content.link)]
[#assign asset2 = model.getAsset()]
[#assign assetMap2 = model.getAssetMap()]
...

Deprecation

For Magnolia 5 all getAsset... templating methods provided by  STKTemplatingFunctions are deprecated. Use the new get methods provided by  DamTemplatingFunctions instead.