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.
This module is deprecated. See Deprecations.
Magnolia's Cumulus DAM Connector allows users to connect a Canto Cumulus DAM to Magnolia. Cumulus is popular, enterprise-grade digital asset management platform that offers digital rights management and many back-end connections, including Adobe Photoshop and InDesign and more. Visit Canto's Cumulus to learn more.
You can use DAM content within a Magnolia website in a manner that resembles working with native Magnolia content. The Cumulus DAM Connector installs the Cumulus Asset app that allows users to browse assets in a remote (Cumulus) DAM.
The Magnolia Cumulus DAM connector module comes with a working configuration pointing to a sandbox account provided by Canto cumulus to try out different assets with your Magnolia installation.
Installing
The Cumulus DAM module is not bundled with Magnolia. You have to add the modules to your webapps yourself with Maven or with the jar files.
<dependency> <groupId>info.magnolia.cumulus</groupId> <artifactId>canto-cumulus-integration</artifactId> </dependency>
Uninstalling
Before uninstalling the module, remove the /server/filters/cumulus
filter node.
Configuring connections
The module canto-cumulus-integration
comes with a working configuration pointing to a sandbox account provided by Canto cumulus. To connect with your own account, change the configuration of the module in the Configuration app.
Add the location of your server in both locations:
/modules/canto-cumulus-integration/rest-client/cumulus/baseUrl
/modules/canto-cumulus-integration/config/
Caching and performance
Magnolia automatically caches all REST calls made to Cumulus if the response calls contain valid cache expire headers with an appropriate time interval describing the response as cacheable. All responses without cache headers are assumed to be non-cacheable.
You can configure a custom cache policy in addition to the code provided by the module. Include an extra cache filter in the REST client configuration. One way to improve performance is to implement a custom cache configuration that stores the details of calls in distributed memory shared by all public nodes. This can help in environments where Magnolia public instances perform a large number of calls.
Rendered images and their corresponding variations are served directly from the Cumulus cloud to the users browsing the website. Direct serving ensures that Cumulus can substitute images in case of DRM restrictions or in case the copyright for a rendered asset or its variation has expired.
How it works
As the owner of a Canto Cumulus DAM system, you administer assets on Cumulus with tools they provide. The Magnolia Cumulus DAM connector enables you to seamlessly integrate Cumulus assets into web pages served by Magnolia.
Displaying Cumulus assets with a Magnolia content app
The connector module provides a content app named cumulus-app
that enables you to browse Cumulus assets from the Magnolia interface. For example, you could use the content app in a Choose dialog to select an asset in a component template. You can see this put into practice below in Example 1 - simple component with an image.
Connecting to Cumulus DAM using REST API
All communication between Magnolia and Canto Cumulus passes through the REST API provided by Cumulus (using the Magnolia REST client module). All calls dealing with Cumulus are made over an authenticated connection using the technical account configured for access between Magnolia and Cumulus. Magnolia does not access any non-public or deprecated API calls of Cumulus.
Based on Magnolia dam-external-app
The Magnolia Cumulus DAM connector is based on the External DAM app module, a Magnolia DAM submodule.
Cumulus Assets app
The Cumulus DAM Connector installs the Cumulus Assets app that allows you to browse all assets in the remote DAM. Such assets can be images, videos or documents stored by other users.
The asset information is read-only becasue the product update API is not exposed by Cumulus DAM Connector. Assets cannot be updated in Magnolia. The only exception is that you can set asset flags to public or not public by publishing or unpublishing assets.
To launch the app in Magnolia, click Edit > Cumulus assets.
Publishing and unpublishing actions
You can publish or unpublish assets as you do with other content. Only published assets are rendered on public instances.
The publish and unpublish actions carried out in Magnolia set a flag in the Cumulus Canto DAM through a REST call.
Using Cumulus assets in templates
Using assets from Cumulus works in the same way as using assets from the Magnolia DAM. You can use
damfn
templating functions to render the asset. If you are new to templating and assets, read How to work with images using damfn.
Note that Magnolia cannot create renditions for assets on the cumulus DAM. If you need images with different sizes, you have to organize them accordingly in the Cumulus DAM.
When you configure a dialog definition to select Cumulus assets, for the link field you must:
- Set the
identifierToPathConverter
property to theAssetCompositeIdKeyTranslator
class. - Set the
appName
tocumulus-app
.
Example 1 - simple component with an image
In this example you create a component template with a single field for an asset. The code is very similar to what is explained on the page How to work with images using damfn; the only difference when compared is in the dialog where you define the asset link field.
Dialog
form: tabs: - name: tabImage fields: - name: image class: info.magnolia.dam.external.app.field.definition.AssetLinkFieldDefinition appName: cumulus-app identifierToPathConverter: class: info.magnolia.dam.external.app.field.AssetCompositeIdKeyTranslator contentPreviewDefinition: contentPreviewClass: info.magnolia.dam.app.ui.field.DamFilePreviewComponent actions: commit: class: info.magnolia.ui.admincentral.dialog.action.SaveDialogActionDefinition cancel: class: info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition
Line 7:
appName
to choose the asset must becumulus-app
.Line 9:
class
property for theidentifierToPathConverter
must beinfo.magnolia.dam.external.app.field.AssetCompositeIdKeyTranslator
.There is no need to specify the property
targetWorkspace
.
Template definition
title: cumulusSimpleImage renderType: freemarker templateScript: /cumulus-templates-examples/templates/components/cumulusSimpleImage.ftl dialog: cumulus-templates-examples:components/cumulusSimpleImage
Template script
<div class="cumulusSimpleImage"> [#assign imgItemKey = content.image!] [#if imgItemKey??] [#assign imgRef = damfn.getAssetLink(imgItemKey)!] [#if imgRef??] <img src="${imgRef}"/> [/#if] [/#if] </div>
Example 2 - extending the component textImage
from MTK
In this example we reuse the component
textImage
which is provided by the MTK module. The template script from the MTK component can be used as it is, but on the dialog, we have to change a few bits. To achieve this we use inherit and override the dialog from mtk, and the template definiton must point to our new dialog.
Dialog
!inherit:mtk:components/textImage title: Cumulus text image form: tabs: - name: tabImage fields: - name: image class: info.magnolia.dam.external.app.field.definition.AssetLinkFieldDefinition appName: cumulus-app identifierToPathConverter: class: info.magnolia.dam.external.app.field.AssetCompositeIdKeyTranslator
mtk:components/textImage
dialog defined in the MTK module, but overrides the image
field on the first tab. Read Reusing configuration or YAML inherit and include for further information.Reference a field by its name
Instead of defining the type of a field using the class
property, you can reference the type using the fieldType
property, which takes the field's short and easy-to-remember alias name as the value.
For example, use fieldType: text
instead of class: info.magnolia.ui.form.field.definition.TextFieldDefinition
.
To view the field alias names, look in the Definitions app. See also Referencing fields.
Template definition
title: cumulusTextImage renderType: freemarker templateScript: /mtk/templates/components/textImage.ftl dialog: cumulus-templates-examples:components/cumulusTextImage
Get the examples from git
You can clone the examples from our git repository. The repository is a light module. In addition to the two components, it contains a page template with an area where you can use the two components.
Clone URL:
https://git.magnolia-cms.com/scm/documentation/cumulus-templates-examples.git