Information for: DEVELOPERS   PARTNERS

Integration: Drupal 8.4 or greater

This page describes the Acquia DAM connector for Drupal versions 8.4 or greater.

The Media: Acquia DAM Drupal module provides bi-directional syncing of media between your Drupal 8-based website and Acquia DAM.

Installing the connector module

Before you can use Acquia DAM, you must connect your website to Acquia by installing the Media: Acquia DAM module. This connector module allows your website to exchange information with Acquia DAM.

For information about installing and enabling Drupal modules on your website, see Installing a Drupal 8 or Drupal 9 module.

If you are upgrading from an older version of the connector module, you must upgrade your database by running the following command:

drush updatedb

Notes

Connecting to Acquia DAM

  1. Sign in to your Drupal website as a user with Administrator permissions.

  2. In the top menu, click Configuration.

  3. Scroll to the Media section, and then click Acquia DAM.

  4. In the Authentication details section, enter your Username, Password, Client ID, and Client secret.

    Notes

    • If you do not have your Client ID or Client secret, contact your account manager.
    • The Username value is a user’s account name for Acquia DAM, and isn’t a user’s email address.
    • The user’s account for Acquia DAM must have the Acquia DAM admin role.
  5. In the Cron settings section, select how frequently your cron job will sync your metadata and assets between your Drupal instance and your Acquia DAM account. The default value is Every hour.

    Important

    You must configure cron, or your assets will not synchronize.

    If you have many assets, synchronizing more frequently may help ensure timely updating of assets. To update the cron interval:

    1. Set the Cron settings to Every cron run.

    2. Create a Drupal scheduled job to run media_acquiadam_asset_refresh every two minutes.

      Add the following Drush command to the cron job:

      drush queue-run media_acquiadam_asset_refresh
      

    This ensures the Acquia DAM synchronization job will run every two minutes through Drupal cron, ensuring that the website processes the sync queue more frequently.

    Note

    The Media: Acquia DAM module does not support realtime or near-realtime asset synchronization with Drupal. Synchronization can take minutes or hours to complete depending on the number of DAM assets synced to Drupal, and the frequency of Drupal cron runs configured.

  6. Click Save configuration.

If you encounter an invalid_grant error, confirm that you entered the correct Username, Password, Client ID, and Client secret.

Preparing to use Acquia DAM with your website

After you have connected your website to Acquia DAM, you must configure a new entity browser and add a new type field to your preferred content type.

Acquia recommends configuring private file storage for your website, since Acquia DAM asset files download locally when added to a piece of content.

Configuring a Media Type

To use Acquia DAM assets in content, you must add a Media Type entry for it. Complete the following steps to add a new media type:

  1. Sign in to your Drupal website as a user with Administrator permissions.
  2. In the top menu, click Structure.
  3. Click Media types, then click Add media type.
  4. Enter a name, such as “Acquia DAM media asset.”
  5. In the Media source menu, select Acquia DAM asset.
  6. Scroll to the bottom of the page and click Save.
  7. In the Media Types list, find the media type you saved, select Manage fields from the Operations dots menu.
  8. Click Add field.
  9. For Add a new field, select Reference > File from the menu.
  10. Enter a label for the field, such as Asset.
  11. Click Save and continue.
  12. Click Save field settings.
  13. Scroll to Allowed file extensions and enter the desired file extensions separated by spaces, such as jpg gif png svg pdf doc docx ppt pptx xls xlsx mp4 mpg mpeg webm.
  14. Click Save settings.
  15. Click the Edit tab.
  16. Scroll to the Field Mappings section, and for the File menu, select the field you created.
  17. Click Save.

Configuring an Entity browser

If you want to access your Acquia DAM assets from the WYSIWYG editor, configure an Entity browser for your Acquia DAM assets using the Acquia DAM widget plugin. Complete the following steps to configure the Entity browser:

  1. Sign in to your Drupal website as a user with Administrator permissions.
  2. In the top menu, click Configuration.
  3. Scroll to the Content Authoring section and click Entity Browsers.
  4. Click Add entity browser.
  5. Enter a label, such as Acquia Dam Entity Browser.
  6. Set Display plugin to Modal. (This is the default.)
  7. Click Next.
  8. Clear any value in both Width of the modal and Height of the modal fields to enable responsive width and height respectively.
  9. Click Next until the Widgets screen appears.
  10. Select Acquia DAM in the Add widget plugin menu.
  11. Click Finish.

To configure the number of items per page in the Entity Browser navigate to Configuration > Media > Acquia DAM (URL path: /admin/config/media/acquiadam).

Adding a content type field

Complete the following steps to add a content type field for your chosen content type:

  1. Sign in to your Drupal website as a user with Administrator permissions.
  2. In the top menu, click Structure.
  3. Click Content types.
  4. For the Basic page row, select Manage fields from the Operations dots menu.
  5. Click Add field.
  6. For Add a new field, select Reference > Media from the menu.
  7. Enter a label, such as DAM asset.
  8. Click Save and continue.
  9. Click Save field settings.
  10. Scroll to the Reference type section, then check Acquia DAM Asset at the bottom of the page.
  11. Click Save settings.

Updating the form display

Complete the following steps to update the form display to include the field you added for your chosen content type:

  1. Sign in to your Drupal website as a user with Administrator permissions.
  2. In the top menu, click Structure.
  3. Click Content > Content types.
  4. For the Basic page row, select Manage form display from the Operations dots menu.
  5. Find the DAM asset field you created earlier. Under the Widget column, select Entity browser.
  6. For the same field, click Settings cog. For the Entity type menu, select Acquia DAM Entity browser.
  7. Click Update.
  8. Scroll to the bottom of the page and click Save. The “Your settings have been saved.” notification will appear at the top of the screen.

Updating display

Complete the following steps to update the content type display to include the field you added for your chosen content type:

  1. Sign in to your Drupal website as a user with Administrator permissions.
  2. In the top menu, click Structure.
  3. Click Content Content types.
  4. For the Basic page row, select Manage display from the Operations dots menu.
  5. Click the Content browser tab.
  6. Find the DAM asset field you created earlier. Under the Format column, select Rendered Entity from the menu.
  7. Scroll to the bottom of the page and click Save.

Configuring Embed for the WYSIWYG editor

  1. Sign in to your Drupal website as a user with Administrator permissions.
  2. Navigate to Configuration > Content Authoring > Text Editor Embed Buttons (URL path: /admin/config/content/embed).
  3. Select Add embed button.
  4. Enter a value for the Label such as Acquia DAM.
  5. For the Embed type, select Entity.
  6. For the Entity type, select Media.
  7. For the Entity Browser, select Acquia DAM Entity Browser.
  8. Optional: Specify a custom Button icon.
  9. Click Save.

Configuring Entity Embed for the WYSIWYG editor

  1. Sign in to your Drupal website as a user with Administrator permissions.

  2. Navigate to Configuration > Content authoring > Text formats and editors (URL path: /admin/config/content/formats).

  3. For Basic HTML, select Configure.

  4. Under Toolbar Configuration, drag and drop the button configured for the Acquia DAM button to the Active Toolbar.

  5. Under Enabled filters, select the Display embedded entities check box.

  6. Under Filter settings, ensure the following text is displayed under Allowed HTML tags:

    <drupal-entity data-entity-type data-entity-uuid data-entity-embed-display data-entity-embed-display-settings data-align data-caption data-embed-button>
    

    By default, it displays as the last line.

  7. Click Save configuration.

After completing these steps, Drupal content authors will be able to click on the button in the WYSIWYG editor to access the Acquia DAM entity browser.

Adding assets through Drupal

You can add assets to Drupal from Acquia DAM using Drupal entities or the WYSIWYG editor.

Adding to a Drupal entity

In this procedure, a asset is being added using a media field.

  1. Sign into your Drupal website as a user with content creation permissions.
  2. Navigate to Content > Add new content.
  3. Select a content type to add.
  4. To select an asset, click Select entities.
  5. The entity browser displays. Click a folder to view the assets inside.
  6. Click an asset, and then click Select assets.

This imports the assets into Drupal.

Adding using the WYSIWYG

Follow this procedure to embed an asset using the WYSIWYG.

  1. Sign into your Drupal website as a user with content creation permissions.
  2. Navigate to Content > Add new content.
  3. Select a content type to add.
  4. Click the WYSIWYG button.
  5. The entity browser displays. Click a folder to view the assets inside.
  6. Click an asset, and then click Select assets.
  7. Select values to choose how your content will be displayed:
    • Display as: Select a display type
    • Align: Where the image is aligned to
    • Caption: A caption for the image
  8. Click Embed.