Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.
This page is about Magnolia 5.3+ / DAM API 2.0+ The way assets are registered and used changed. If you work with Magnolia 5.2.x or earlier, see DAM API 1.x.
The DAM API provides the basic mechanism for the abstraction of the storage location of an asset. The API:
Here are the major changes
AssetProviderRegistry
replaces DamManager
. See DAM and the STK and DAM templating for how to use assets in your templates.AssetProvider
and Asset
API now supports folders. This makes navigating the asset hierarchy via the API easier.The changes have no impact on the STK. There is no need to modify Freemarker scripts because the new DAM API is abstracted from STK.
The diagram provides an overview of how the main interfaces and classes of the DAM API relate.
ItemKey
or MediaType
it is responsible for:AssetProvider
.AssetRenderer
.Folder
s and Asset
s from a particular source. Specifics of the storage of these items are left to implementations. While most provider implementations only use the ItemKey.assetId
field of keys passed to the various get
methods, the entire key object is passed for consistency and flexibility. This makes it possible to implement, for example, delegating and aggregating providers.AssetProviders
that are aware of paths, for example JCR, CMIS, File system etc. Not all providers need or want to implement these features. The term "path" here should be taken "with a pinch of salt". It could, for example, be a single name or a "relative" path if the provider serves assets from a subset of its underlying data source.AssetRenditions
by bridging an asset's data and some type of converter. AssetRenderers
can be provided by AssetProviders
if the AssetProvider
itself (or the underlying system) is capable of managing the conversion/translation, or via a "global" registry. AssetProviderRegistry.getRendererFor(info.magnolia.dam.api.Asset, com.google.common.net.MediaType)
provides the entry point. It looks up in provider, then in its own registry, and bridges to other possible conversion mechanisms that are independent of Magnolia DAM.Asset
is a digital resource with associated metadata.Folder
represents a structural item holding Asset
s. Depending on the provider, this can be directly mapped to the concept of folders/directories (JCR, FileSystems etc.), and for other types it may map to the concept of albums, playlists, sets, etc.Asset
and Folder
. AssetProvider
. Use new AssetQuery.Builder()...build()
to construct instances. AssetRendition
is a "view" on a asset for a specific MediaType
. It can be a simple resize of an image, or a document conversion.PathAwareAssetProvider
for hierarchical
). If support for write operations is added, this enum will be extended with new capabilities. MediaType
s that the implemented AssetProvider
provides. Item
. AssetQuery
that provides a fluent API. Asset
and Folder
is identified by its provider's ID and its provider-specific ID (i.e the ID with which the provider can uniquely identify the asset). Asset
by extending this interface. The AssetProvider
should implement support for those. Specific metadata interfaces should expose methods with explicit names and return types, and ideally provide property descriptions in the Javadocs. Metadata is retrieved through an Asset
by passing the specific type of metadata, i.e, a class object that extends this interface.getContributor
,getCoverage
, getCreated
, getCreator
, getDate
, getDescription
, getFormat
, getIdentifier
, getLanguage
, getModified
, getPublisher
, getRelation
, getRights
, getSource
, getSubject
, getTitle
, getType
.AssetMetadata
. Methods: getHeight
, getWidth
.DAM 2.0 introduces the com.google.common.net.MediaType
class included in the Google Guava library. This class replaces DAM 1.x media types that linked MimeTypes
and MediaTypes
by configuration and RegexVoters
.
Here's the class description from the Guava Javadoc.
Represents an Internet Media Type (also known as a MIME Type or Content Type). This class also supports the concept of media ranges defined by HTTP/1.1. As such, the
*
character is treated as a wildcard and is used to represent any acceptable type or subtype value. A media type may not have wildcard type with a declared subtype. The*
character has no special meaning as part of a parameter. All values for type, subtype, parameter attributes or parameter values must be valid according to RFCs 2045 and 2046.All portions of the media type that are case-insensitive (type, subtype, parameter attributes) are normalized to lowercase. The value of the
charset
parameter is normalized to lowercase, but all others are left as-is.Note that this specifically does not represent the value of the MIME
Content-Type
header and as such has no support for header-specific considerations such as line folding and comments.For media types that take a charset the predefined constants default to UTF-8 and have a "_UTF_8" suffix. To get a version without a character set, use
withoutParameters()
.
To access AssetProviderRegistry
from your custom module, adapt your pom
and module descriptor XML files to include a dependency. You can simply inject or use components to access the AssetProviderRegistry
private final AssetProviderRegistry providerRegistry; // By Injection @Inject public MyFunctions(AssetProviderRegistry providerRegistry) { this.providerRegistry = providerRegistry; } // Or using Components public void myCustomMethod() { this.providerRegistry = Components.getComponent(AssetProviderRegistry.class); }
AssetProvider
has “capabilities” (
AssetProviderCapability
). Some implementations will not support all features. This can be used to drive a UI to enable/disable certain actions or UI elements. Implementations should still throw exceptions when those unsupported operations are called. (although this may not consistently be the case, for example when aggregating search results from different providers.)ItemKey
is a specific type (composed of provider id and asset id) rather than a "magic string". It is passed to most methods, rather than the assetID
string. This allows for aggregation/delegation in specialized providers.AssetProviders
are registered by configuration in the DAM Core module.
Item
is the main parent definition of a Folder
and an Asset
. Asset
is the abstract representation of an binary document:Folder
is the abstract representation of a folder that contains Asset
Implementation notes:
Items,
Folders
and Assets
mimic the JCR API, but there are subtle differences that are highlighted in the Javadocs.Items
, Folders
and Assets
are meant to be implemented "lazily". Implementations will typically keep a reference to their provider. For example, the JCR implementation simply keeps a reference to the corresponding Node
instance, and delegates to it "on demand". Contrary to DAM API 1.x, a getTitle()
method on JcrAsset
just delegates to node.getProperty("title")
, rather than eagerly loading all the properties and acting like a POJO later on. An AssetRendition
is a transformation of an Asset
. The AssetRenderer
provides AssetRenditions
by bridging an Asset's
data and some type of converter.
AssetRenderer
can be provided by AssetProvider
when the conversion/translation can be managed by the AssetProvider
itself (or its underlying system), or via a "global" registry.AssetProviderRegistry.getRendererFor(Asset
asset,MediaType
mediaType)
, provides the entry point. It looks up in the provider then in its own registry, and bridges to other possible conversion mechanisms that are independent of the Magnolia DAM.AssetRenderers
are registered by configuration in the DAM Core module.
The DAM JCR API classes reside in the DAM JCR module and implement the DAM API for JCR assets that are stored in the dam workspace and accessible in the Assets app <link>.
AssetProvider
that delivers assets for the dam
workspace. Extends AbstractAssetProvider
and implements PathAwareAssetProvider
.
Item
. Extends AbstractItem<JcrAssetProvider>
. Asset
definition. Extends AbstractJcrItem
.Folder
definition. Extends AbstractJcrItem
.Asset
: Represents the node type mgnl:asset
. Fields: caption
, comment
, copyright
, description
, language
, master
, name
, provider_type
, subject
, title
, type
.AssetResource
: Represent the resource node bound to an Asset
. Fields: data
, extension
, filename
, height
, mimetype
, name
, ressource_name
, size
, width
.Node.getPrimaryNodeType()
:AssetNodeTypes.Asset.NAME
NodeTypes.Folder#NAME
.Extends info.magnolia.jcr.predicate.AbstractPredicate<javax.jcr.Node>
.
default_jcr_provider_id
, workspace
.In the STK, assets are rendered by STKAssetRenderer
that delegates to the Imaging module to generate renditions. See DAM and the STK for more.
Magnolia 5.3.2+ / DAM JCR 2.0.2+ In order to access a custom property defined under a JCR Asset node,
JcrAsset
provides a public getter:
/** * JcrAsset specific implementation that lets you access a property value linked to an asset node. * This requires an open session. * * @return property value Object if the property exists or null otherwise. */ public Object getProperty(String propertyName) { return PropertyUtil.getPropertyValueObject(getNode(), propertyName);
DublinCore
. Fields: dc_contributor
, dc_coverage
, dc_creator
, dc_publisher
, dc_relation
, dc_source
, dc_subject
, dc_type
. Methods: getContributor
, getCoverage
, getCreated
, getCreator
, getDate
, getDescription
, getFormat
, getIdentifier
, getLanguage
, getModified
, getPublisher
, getRelation
, getRights
, getSource
, getSubject
, getTitle
, getType
.MagnoliaAssetMetadata
definition. Methods: getHeight
, getWidth