Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.

The DAM core module is a Magnolia Maven module.

  • It has a module class -  DamCoreConfiguration  - which implements  ModuleLifecycle .
  • It contains (and registers) the  DamDownloadServlet .
  • Provides an implementation of  AssetProviderRegistry .
  • The module is configured in /modules/dam/config


Installing

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-core</artifactId>
  <version>2.4.3</version>
</dependency>

Pre-built JARs are also available for download. See Installing a module for help.

Asset providers and renderers

In order to have a working DAM you must have configured at least: 

  • an  AssetProvider
  • an  AssetRenderer

Configuring AssetProvider

To enable DAM at least one AssetProvider must be configuread as subnode of /modules/dam/config/providers/.

Node nameValue

 modules


 dam


 config


 providers


 example-provider


 class

com.example.dam.MyAssetProvider

 identifier

 foo
class

required

A class which must implement AssetProvider

identifier

required

The identifier of the asset provider. Must be unique within all asset providers.

Configuring an AssetRenderer

AssetRenderer  objects can be configured:

  • globally 
  • or per AssetProvider. 

When an asset rendition is requested, AssetProviderRegistry#getRendererFor(Asset asset, MediaType to)  first is looking for a provider specific renderer but will fallback to the globally defined renderer if no specific can be found.

Node nameValue

 modules


 dam


 config


 providers


  example-provider


 renderers


 imaging


 class

com.example.dam.ImagingBasedAssetRenderer

 class

com.example.dam.MyAssetProvider

 identifier

 foo

 renderers


 noOp


 class

info.magnolia.dam.core.NoOpAssetRenderer

The example configuration above has 2 renderers defined: 

  • /modules/dam/config/providers/example-provider/ renderers/imaging configures a renderer for images specifically for the asset provider example-provider.
  • /modules/dam/config/ renderers/noOp is a global fallback if a provider lacks a renderer for the requested media type.

NoOpAssetRenderer

The module magnolia-dam-core provides  NoOpAssetRenderer  which can be used to define global AssetRenderer. Per default, NoOpAssetRenderer does only wrap the original Asset.

NoOpAssetRenderer is registered by 

Implementation specific configuration

magnolia-dam-core is not taking care about the used AssetProvider implementation.

Specific asset provider and renderer should rather be configured from a module which contains a specific implementation but not from magnolia-dam-core itself.

Please read Magnolia dam JCR implementation configuration to get a complete example of a specific configuration.

Download servlet

DamDownloadServlet handles asset downloads. The main task is to retrieve an Asset Object based on the current URI:

  • If no Asset is found, an error is sent to the response.
  • If an Asset is found, the response header is set and the asset binary is put in the response.

The servlet is backwards compatible and maps static UUIDs to the new DAM format.

DamDownloadServlet is registered in the filter chain at /server/filters/servlets/DamDownloadServlet.

Node nameValue

 server


 filters


 context


 ...


 servlets


 ClasspathSpoolServlet


 log4j


 DamDownloadServlet


 mappings


 -dam--


 pattern

/dam/*

 -dam-static--


 pattern

/dam-static/*

 parameters


 class

info.magnolia.cms.filters.ServletDispatchingFilter

 comment

DAM download servlet 

 enabled

true

 servletClass

info.magnolia.dam.core.download.DamDownloadServlet 

 servletName

DamDownloadServlet

Content disposition

Content-disposition is a HTTP header. If the Content-disposition field is set in a HTTP response header, the browser opens the "save file as" dialog instead of rendering the requested resource.

Per default, DamDownloadServlet serves assets with set Content-Disposition header. However, it is possible to define exceptions to omit the content disposition header.

Disabling content disposition headers per mime type

DAM standard configuration already defines 2 exceptions based on mime type:

  • application/x-shockwave-flash
  • video/mp4

To disable the Content-Disposition header for other content types, add their MIME types to /dam/config/contentDisposition/contentType/rejected.

Node nameValue

 modules


 dam


 config


 contentDisposition


 contentType


 rejected


 1

application/x-shockwave-flash

 2

video/mp4 

 class

info.magnolia.voting.voters.ResponseContentTypeVoter

 class

info.magnolia.voting.voters.VoterSet

Nodes and properties:

  • contentDisposition: Defines content disposition header exceptions.
    • contentType: Arbitrary node name
      • rejected: Content map of MIME types for which content disposition headers are not served.
      • class: ResponseContentTypeVoter is a voter that checks the content type set on the response object against a list of allowed and/or rejected content types. It is typed to Object, as it can vote on both a passed HttpServletRequest, or the current MgnlContext.webContext, if any.
    • class VoterSet supports a set of voters. The voting can be set, as well the returned level. If the level is not set (0) the votings result is returned.

Disabling content disposition headers based on path

To disable serving Content-Disposition headers based on path:

  1. Create a new node inline under contentDisposition.
  2. Under the new content node, create three property nodes:
    • class and set the value to info.magnolia.voting.voters.URIStartsWithVoter.
    • not and set the value to true.
    • pattern and set the value to /dam/inline.
  3. Under the contentDisposition node add an op property and set the value to and. This acts as an operator between voters and is only necessary if there you have more than one voter in the set.

This will configure all files in folder inline to be sent without content disposition headers. The new content node should look like this:

Node nameValue

 contentDisposition


 contentType


 inline


 class

info.magnolia.voting.voters.URIStartsWithVoter

 not

true

 pattern

/dam/inline

 class

info.magnolia.voting.voters.VoterSet

 op

and