Probably the biggest problem with the former media support was its high fragmentation. Media could be stored in different locations, both as sub-nodes of content nodes, or in the dms workspace. A goal of the new DAM is that all assets are stored in one centralized location so that users can have an overview of all their media, work with their media, and manage their media. But we don't want to make the day-to-day use any more difficult. A user is still able to upload a media item directly in the page editor - it will just be stored in the centralized workspace instead of under the pages content node.
Features of DAM:
- The asset reference is stored in a straightforward way. While following the old way it was required to have to properties for pointing to an asset (e.g. "image": dms - for defining the correct DAMHandler, "imageDmsUUID" - for actual reference) now the reference to the node in the DAM workspace is enough (e.g. "image": <UUID>).
- The responsibility of resolving the DAM asset is encapsulated in the DAM module (used to be incorporated in Standard Templating Kit).
- mgnl:asset node type was introduced for assets. Mandatory child node with the name jcr:content of type jcr:resource points to the actual data.
DAM Module Implementation Diagram
Typical Use Case
Let us consider an arbitrary TextImage component that resides on the page. Its image part is backed up by an asset. In order to render he following steps have to be completed:
- Standard Templating Kit (STK) which provides the template for our TextImage component makes a queries the DAM module for an asset.
- The argument of the query is the asset UUID which is stored in the "image" property of TextImage.
- STK templating function obtain the reference to the DAM module through Dam class which acts as a dispatcher for assets.
- Dam locates the node in the workspace and retrieves the correct AssetProvider (referenced in asset node).
- AssetProvider assembles the DamAsset based on the asset node from the workspace.
- Sets the Meta-Data source which allows for flexible changing the ways of how meta-data is fetched and from where (typically - from the asset node internals, but could be from wherever).
- Provides direct access to binary media data (again, typically - from the internals of asset node but potentially - from external places as well).
- Asset is returned to STK.
- Normally we operate not on the original asset but rather on its variations.
- Asset provides the variations of itself but that requires the context info (e.g. current site/current theme).
- Modules that obtain such information (like STK) should know how to implement the VariationProvider and set it to Asset.
- During rendering phase asset it transferred to the ImagingModule that based on the asset media and meta-data generates a URL to the generated image.
- It is not possible to modify media of an asset that is used in some component on some page. If there's still a need to use the modified version then an asset variant is created.
- Variant is basically a verbatim of an original master which in this case is called a Master.
- Variant references it master with a WeakReference (master property in mgnl:asset node type definition).
- Asset variants are created by means of CreateAssetVariantAction which creates the copy of the node and sets the reference to the source asset node automatically.
- It is not possible to create the variant of an asset that itself is a variant.
- It is currently possible to look up the original node for a copy by means of SelectMasterAssetAction.
Searching for the uses of an asset
AssetUsesSearchHelper class provides the approach allowing for determining whether an asset was used somewhere in the website workspace.
- In assets app, double-click on an image asset which has not been used. A view of the asset’s image plus its metadata opens in a SubApp. Click edit, Editor opens. Click “Crop” Action. Choose a proper crop. Save.
- As above, but for an image asset which already has a use. (A dialog )
- In Assets app, select an image, click “Copy” action. Change the new image’s crop. Repeat this so there are two copies of the original asset. Select the original asset, click “Select copies” action: both copies are displayed in the search view. Select one of the copies, click “Show original”: the original asset is displayed in the search view.
- In Assets app, select an asset that is used on two different pages. Click “show uses” action: A "uses" subapp is displayed which shows a list of each use including details such as where it is used.
Asset editing is implemented in info.magnolia.dam.app.assets.editor.AssetEditorSubApp.
- Currently only crop operation is supported in editor.
- In case the asset is used in some page in the website asset-media modification is not possible (textual information is still possible).
For migration details please see: Concept - DAM migration tasks