DAM 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.
   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.

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.