Versions Compared

Old Version 5

changes.mady.by.user Julie Legendre

Saved on

compared with

New Version Current

changes.mady.by.user Julie Legendre

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: set levels

...

  • Javadoc resource link
    0info.magnolia.dam.api.AssetProviderRegistry
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.AssetProviderRegistry
    renderTypeasynchronous
    is the main entry point. Given an ItemKey or MediaType it is responsible for:
    • Finding the correct AssetProvider.
    • Finding the correct AssetRenderer.
  • Javadoc resource link
    0info.magnolia.dam.api.AssetProvider
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.AssetProvider
    renderTypeasynchronous
    : Exposes Folders and Assets 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.
  • Javadoc resource link
    0info.magnolia.dam.api.PathAwareAssetProvider
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.PathAwareAssetProvider
    renderTypeasynchronous
    : Exposes specific operations for 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.
  • Javadoc resource link
    0info.magnolia.dam.api.AssetRenderer
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.AssetRenderer
    renderTypeasynchronous
    : Provides 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.
  • Javadoc resource link
    0info.magnolia.dam.api.Asset
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.Asset
    renderTypeasynchronous
    : An Asset is a digital resource with associated metadata.
  • Javadoc resource link
    0info.magnolia.dam.api.Folder
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.Folder
    renderTypeasynchronous
    : A Folder represents a structural item holding Assets. 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.
  • Javadoc resource link
    0info.magnolia.dam.api.Item
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.Item
    renderTypeasynchronous
    : Defines a common interface for Asset and Folder. 
  • Javadoc resource link
    0info.magnolia.dam.api.AssetQuery
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.AssetQuery
    renderTypeasynchronous
    : Represents a query to an AssetProvider. Use new AssetQuery.Builder()...build() to construct instances. 
  • Javadoc resource link
    0info.magnolia.dam.api.AssetRendition
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.AssetRendition
    renderTypeasynchronous
    : An AssetRendition is a "view" on a asset for a specific MediaType. It can be a simple resize of an image, or a document conversion.

...

  • Javadoc resource link
    0info.magnolia.dam.api.AssetProviderCapability
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.AssetProviderCapability
    renderTypeasynchronous
    : Clients can ask a provider if they support a certain feature before attempting to use it. Typically, this would enable/disable certain UI features. In some cases, this will also indicate that client code can cast to a specific interface. (e.g. PathAwareAssetProvider for hierarchical). If support for write operations is added, this enum will be extended with new capabilities. 

...

  • Javadoc resource link
    0info.magnolia.dam.api.AbstractAssetProvider
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.AbstractAssetProvider
    renderTypeasynchronous
    :     Convenient abstract base class for implementations. Enables configuration of MediaTypes that the implemented AssetProvider provides.
  • Javadoc resource link
    0info.magnolia.dam.api.AbstractItem
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.AbstractItem
    renderTypeasynchronous
    : Common superclass for any dam Item.
  • Javadoc resource link
    0info.magnolia.dam.api.AssetQuery.Builder
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.AssetQuery.Builder
    renderTypeasynchronous
     : A builder for AssetQuery that provides a fluent API.
  • Javadoc resource link
    0info.magnolia.dam.api.ItemKey
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.ItemKey
    renderTypeasynchronous
    : A composite key. In the DAM every 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).

Metadata interfaces

  • Javadoc resource link
    0info.magnolia.dam.api.metadata.AssetMetadata
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.metadata.AssetMetadata
    renderTypeasynchronous
    : A common interface for asset metadata. Different types of metadata can be exposed through 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.
  • Javadoc resource link
    0info.magnolia.dam.api.metadata.DublinCore
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.metadata.DublinCore
    renderTypeasynchronous
    : A collection of Dublin Core metadata names. Extends AssetMetadata. Methods: getContributor,getCoverage, getCreated, getCreator, getDate, getDescription, getFormat, getIdentifier, getLanguage, getModified, getPublisher, getRelation, getRights, getSource, getSubject, getTitle, getType.
  • Javadoc resource link
    0info.magnolia.dam.api.metadata.MagnoliaAssetMetadata
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.metadata.MagnoliaAssetMetadata
    renderTypeasynchronous
    : Defines Magnolia-specific metadata. Extends AssetMetadata. Methods: getHeight, getWidth.

MediaType

DAM 2.0 introduces the com.google.common.net.MediaType  class included in the Google Guava library. 

...

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().

Accessing the DAM API

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

Code Block
    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” (
    Javadoc resource link
    0info.magnolia.dam.api.AssetProviderCapability
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.api.AssetProviderCapability
    renderTypeasynchronous
    ). 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 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.
Info

AssetProviders are registered by configuration in the DAM Core module.

Items, assets and folders

  • 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:

  • To some extent, 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". 

...

  • Javadoc resource link
    0info.magnolia.dam.jcr.JcrAssetProvider
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.jcr.JcrAssetProvider
    renderTypeasynchronous
    : AssetProvider that delivers assets for the dam workspace. Extends AbstractAssetProvider and implements PathAwareAssetProvider. 
  • Javadoc resource link
    0info.magnolia.dam.jcr.AbstractJcrItem.jcr.AbstractJcrItem
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.jcr.AbstractJcrItem
    renderTypeasynchronous
    : JCR implementation of an Item. Extends AbstractItem<JcrAssetProvider>. 
  • Javadoc resource link
    0info.magnolia.dam.jcr.JcrAsset
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.jcr.JcrAsset
    renderTypeasynchronous
    : JCR implementation of the Asset definition. Extends AbstractJcrItem.
  • Javadoc resource link
    0info.magnolia.dam.jcr.JcrFolder
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.jcr.JcrFolder
    renderTypeasynchronous
    : JCR implementation of the Folder definition. Extends AbstractJcrItem.
  • Javadoc resource link
    0info.magnolia.dam.jcr.AssetNodeTypes
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.jcr.AssetNodeTypes
    renderTypeasynchronous
    : Constants and convenience methods for asset node types.
    • 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.
  • Javadoc resource link
    0info.magnolia.dam.jcr.JcrItemNodeTypePredicate
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.jcr.JcrItemNodeTypePredicate
    renderTypeasynchronous
    : Predicate filtering assets nodes (folders and assets) based on the following Node.getPrimaryNodeType():
    • AssetNodeTypes.Asset.NAME
    • NodeTypes.Folder#NAME.

...

  • Javadoc resource link
    0info.magnolia.dam.jcr.DamConstants
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.jcr.DamConstants
    renderTypeasynchronous
    : Defines commonly used constants for the DAM.JCR module. Fields: default_jcr_provider_id, workspace.

...

In order to access a custom property defined under a JCR Asset node, 

Javadoc resource link
0info.magnolia.dam.jcr.JcrAsset
rangeHigherVersion2.4
classNameinfo.magnolia.dam.jcr.JcrAsset
renderTypeasynchronous
provides a public getter: 

...

  • Javadoc resource link
    0info.magnolia.dam.jcr.metadata.JcrDublinCore
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.jcr.metadata.JcrDublinCore
    renderTypeasynchronous
    : JCR implementation of 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.
  • Javadoc resource link
    0info.magnolia.dam.jcr.metadata.JcrMagnoliaAssetMetadata
    rangeHigherVersion2.4
    classNameinfo.magnolia.dam.jcr.metadata.JcrMagnoliaAssetMetadata
    renderTypeasynchronous
    : Base JCR implementation of the MagnoliaAssetMetadata definition. 
    • Methods: getHeight, getWidth

DAM templating functions

As a template developer, also have a look at damfn, a set of methods which can be used in freemarker scripts to easy access assets, asset renditions, and so on.

...