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

The DAM API in Magnolia 5.0 provides the basic mechanism for the abstraction of the storage location of an asset. The API:

  • Supports assets stored in the dam workspace, so-called "jcr" assets. This will be extended in the future to allow for external storage providers.
  • Is used primarily in templating, templates and models. It provides read-only access to assets managed in the Assets app 1.x. 


The DAM API features:

  • Assets referenced by a composite key that is comprised of a provider id and a provider-specific asset id. This structure allows all assets to be treated in the same manner, regardless of the asset storage location.
  • The new concept of an original. When a file is uploaded to the DAM, an asset and an original are created. The original contains the uploaded binary data and is never changed.
  • Customizable metadata support. By default the Dublin Core Metadata Element Set is supported, but the API can be extended to support other standards like IPTC.

Architecture

The following diagram provides an overview of how the main interfaces and classes of the DAM API relate:

  • DamManager is the main entry point. Given an AssetId, it is responsible for:
    1. Finding the correct AssetProvider.
    2. Providing the specified Asset.
  • AssetProvider: Implemented classes are responsible for populating Asset properties based on specific storage. The default implementation  JcrAssetProvider creates Assets based on JCR nodes. 
  • Asset: Implemented classes are simple POJOs that contain the information needed to manipulate and display Assets. This includes binary content and access to metadata.
  • AssetMetadata: An Asset may be linked to one or more metadata standards, for example Dublin Core and Exif.  By default only Dublin Core is supported, but the API provides the possibility to access any supported metadata type from an Asset.
  • Rendition: Renditions are transformations of an Asset. The Rendition is provided by an  AssetRenderer . Renderers are configured per media type.

DamManager

DamManager  is the entry or access point for other modules that use the API. 

In DamManager an Asset is identified by:

  • compositeKey: This is a composite Identifier. The first part of the identifier refers to the AssetProvider Id and the second part to the Asset Id. DamManager directly calls the defined AssetProvider to retrieve the Asset.
  • folderIdentifier : DamManager iterates all registered active AssetProviders to get an Asset or list of Assets.

(warning) To manipulate the composite identifier, the utility class  DamIdParser is provided. It can be used to create, check or get assetProviderIdentifier or assetIdentifier from a compositeKey.

Accessing DamManager

To access DamManager from your custom module, adapt your pom and module descriptor XML files to include a dependency. You can simply inject or use components to get DamManager.

 private DamManager damManager;
    // BY Injection
    @Inject
    public CustomFunction(DamManager damManager) {
        this.damManager = damManager;
    }
    // OR by using Components
    public void myCustomMethod() {
        this.damManager = Components.getComponent(DamManager.class);
    }

AssetProvider

AssetProvider uses AssetBuilder and AssetMetadataBuilder to convert a JCR Node to an Asset and AssetMetadata.

A class that implements  AssetProvider is responsible for creating an Asset based on a specific storage or service. For example,  JcrAssetProvider creates assets from the dam JCR workspace.

An AssetProvider retrieves an Asset based on either:

  • assetIdentifier: The second part of the compositeKey, i.e. without the assetProviderIdentifier. In case of the JCR assets the assetIdentifier is the node identifier.
  • folderIdentifier: In the JCR context this is either an asset node path or an AssetFolder node path.

AssetProvider uses  AssetBuilder and AssetMetadataBuilder to convert a JCR node into an Asset and AssetMetadata.

Asset

An  Asset is a simple POJO with getters and setters (exposed in  AbstractBaseAsset ). The specific AssetProvider is responsible for:

  • Correctly getting and setting the properties.
  • Creating the correct implementation of the specified AssetMetadata based on the AssetMetadataType .

AssetMetadata

The specific  AssetMetadata implementation is created and linked to the Asset based on the specified  AssetMetadataType .

The AssetMetadata linked to an asset can change at any time and the assetMetadata.getMetadata(...) call is performed dynamically. The following code snippet performs the call,

@Override
public AssetMetadata getMetadata(String metadataType) throws AssetMetadataTypeNotSupportedException {
    return assetMetadataBuilder.createAssetMetadata(assetNode, metadataType);
}

Renditions and media types

A Rendition is a transformation of an Asset. A MediaType is defined based on the Asset MimeType and is related to an  AssetRenderer . The renderer is responsible for creating the correct Rendition link, among others. This is equivalent to a variation link in Magnolia 4.5.

The link between the MimeType and the MediaType is established by configuration and voters (class: RegexVoter ).

By default all MediaTypes are linked to the  JcrAssetRenderer class. The Standard Templating Kit has its own renderer, STKAssetRenderer , that uses the Imaging module to generate renditions for images. During STK installation the dam configuration is modified to set the STKAssetRenderer for MediaTypes/image. This renderer supports the STK image variation concept. Here are two example MediaType configurations in  /modules/dam/config/mediaTypes.

Node nameValue
 dam 

 config

 

 mediaTypes

 

 image

 

 voter

 

 class

info.magnolia.dam.util.RegexVoter

 pattern

image/.*

 uploadConfig

 

 rendererClass

info.magnolia.module.templatingkit.dam.STKAssetRenderer

 audio

 

 voter

 

 class

info.magnolia.dam.util.RegexVoter

 pattern

audio/.*

 uploadConfig

 

 rendererClass

info.magnolia.dam.providers.jcr.JcrAssetRenderer

The following mediaTypes are supported:

MediaTypeRegexVoter
imageimage/.*
audioaudio/.*
videovideo/.*
documenttext/
application.*(powerpoint)
application.*(msword)
application.*(excel|xls)
application/pdf
flashapplication/x-shockwave-flash
applicationapplication/.*

Configuring custom MediaTypes

You can extend the media type configuration to suit your needs. Here are two examples that you can adapt.

Example 1: Handle 'wordperfect' as document

  1. Go to Configuration/modules/dam/config/mediaTypes/document/voter:
  2. Add a node wordperfect_voter.
  3. Add three properties:
    1. class and set the value to info.magnolia.dam.util.RegexVoter.
    2. level and set the value to 2. (warning) This is mandatory because there is an existing voter pattern defined for application/.* under /mediaTypes/voter/application. If two MediaTypes with the same voter value exist, the first one found is returned
    3. pattern and set the value to application/wordperfect. This defines a regex pattern applicable to wordperfect MimeTypes.
Node nameValue

 mediaTypes

 

 document

 

 voter

 

 wordperfect_voter

 

 class

info.magnolia.dam.util.RegexVoter

 level

2

 pattern

application/wordperfect

Example 2: Handle 'json' as json application

(warning) For this example you need to create a custom rendererClass pointing to your own implementation of AssetRenderer .

  1. Go to Configuration/modules/dam/config/mediaTypes:
  2. Add a node json
  3. Add a rendererClass property and set the value to the fully qualified name of your rendererClass, for example info.magnolia.module.json.renderer.JsonRenderer.
  4. Add a node /voter under the /json node.
  5. Add three properties to the /voter node:
    1. class and set the value to info.magnolia.dam.util.RegexVoter.
    2. level and set the value to 2.
    3. pattern and set the a regex pattern applicable to jason MimeTypes, for examples application/json.
Node nameValue

 mediaTypes

 

 jason

 

 voter

 

 class

info.magnolia.dam.util.RegexVoter

 level

2

 pattern

application/jason

 rendererClass

info.magnolia.module.jason.renderer.JasonRenderer

 

Utility classes

See DAM templating 1.x for details and usage of the DAM utility classes.

info.magnolia.dam.asset.renderer.AssetRenderer