style
content

Configuring Adobe Experience Manager Assets Sidekick Plugin

This article lists down the steps to configure the Experience Manager Assets Sidekick plugin. With this plugin, you can use assets from your Experience Manager Assets repository while authoring documents in Microsoft Word or Google Docs. For more information on authoring experience while using this plugin, please see Adobe Experience Manager Assets Sidekick Plugin.

Note: Using non-image assets such as Videos and PDF documents is in an Early Adopter program. Find more details here.

Add configuration to your AEM Sidekick

To enable the Assets plugin in your AEM Sidekick for website authors, please follow these steps in your project’s GitHub.

  1. The Sidekick configuration file is located at tools/sidekick/config.json in your AEM Franklin site's GitHub repository. If it does not already exist, create it. For more details, please refer to this document on extending AEM Sidekick.
  2. The important part is the "assets-library" plugin. You can either add the plugin definition to your existing configuration, or replace your configuration with the content below. Please note that you should provide a title for the plugin that website authors will understand (“My Assets” in the example below)
{
	"id": "asset-library",
	"title": "My Assets",
	"environments": [
	"edit"
	],
	"url": "https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/franklin/asset-selector.html",
	"isPalette": true,
	"includePaths": [ "**.docx**" ],
	"passConfig": true,
	"paletteRect": "top: 50px; bottom: 10px; right: 10px; left: auto; width:400px; height: calc(100vh - 60px)"
}
  1. Make sure to commit the above sidekick config in your project's Github repo.
  2. Open up the AEM sidekick in your Microsoft Word or Google Doc. You should see the "My Assets" button in it.

Advanced configurations

You can optionally customize the AEM Assets sidekick plugin by specifying query parameters in the asset selector URL in the Sidekick config.json file. The following parameters are supported:

rail (optional)

Permissible Values: true/false

Use this parameter to toggle the rail view of the Asset Selector. By default, the “rail” view navigation is used, which is more compact and offers search-only experience. If you set the parameter to “?rail=false”, a tree view left panel is shown with the repository folder hierarchy letting users browse for assets in addition to searching.

Please note that the folder hierarchy view occupies some extra space. To accommodate for it, you may have to increase the width of the Asset Selector panel.
Here is an example configuration:

{
    "id": "asset-library",
    "title": "My Assets",
    "environments": [ "edit" ],
    "url": "https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/franklin/asset-selector.html?rail=false",
    "isPalette": true,
    "includePaths": [ "**.docx**" ],
    "passConfig": true,
    "paletteRect": "top: 50px; bottom: 10px; right: 10px; left: auto; width:800px; height: calc(100vh - 60px)"
}

The Asset Selector component leverages micro-frontend Asset Selector that is instrumented to integrate with Sidekick for easy integration. To learn more, see Micro-Frontend Asset Selector documentation.

extConfigUrl (optional)

It allows extending AEM Assets Sidekick Plugin by specifying the complete URL where the configuration is hosted, particularly useful for scenarios where the configuration resides at a different location than the project's domain. To configure extConfigUrl, include it in the sidekick JSON configuration of the extension.

Here is an example configuration:

{ 
  "project": "franklin-asset-selector", 
  "plugins": [ 
	{ 
  	"id": "asset-library", 
  	"title": "AEM Assets Library", 
  	"environments": ["edit"], 
  	"url": "https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/franklin/asset-selector.html?extConfigUrl=https://<your-config-server>/config.json", 
  	"isPalette": true, 
  	"includePaths": ["**.docx**"], 
  	"passConfig": true, 
  	"paletteRect": "top: 50px; bottom: 10px; right: 10px; left: auto; width:400px; height: calc(100vh - 60px)" 
	} 
  ] 
}

Note: Ensure that the URL supplied in parameter extConfigUrl , is accessible and that Cross-Origin Resource Sharing (CORS) is enabled for the domain experience.adobe.com. If the configuration is hosted on the Edge Delivery Services project, refer to the documentation for detailed instructions on configuring CORS for hosted configurations.

Extend AEM Assets Sidekick Plugin

This section offers comprehensive instructions on customizing the AEM Assets Sidekick Plugin using extension points and configuring it to meet your custom requirements.

Extension Points

The Adobe Experience Manager Assets Sidekick Plugin provides extension points that empower you to tailor its behavior to your needs. These extension points enhance the plugin's functionality and adapt it to your organization's unique demands. Below are the supported Extension Points:

blockName

Defines the block name for different MIME types.

Example Configuration (Video Type Assets):
{ 
	"blockName": [ 
    	{ 
        	"mimeType": "video/*", 
        	"value": "Core Embed" 
    	} 
	] 
}

This configuration allows users to change the Block Name for Video type assets from default “Embed” to “Core Embed”.

copyMode

Defines the copy mode for different MIME types.

Example Configuration (Image Type Assets):
{ 
	"copyMode": [ 
    	{ 
        	"mimeType": "image/*", 
        	"value": "reference" 
    	} 
	] 
}

This configuration enables users to pick images from the Assets Selector as a link when pasting it into a Word document.

Note: Once the config is enabled, you’d also need to ensure appropriate handling in your site’s front-end code to convert such image links to <picture/> tag with appropriate srcset - Find more details here

blockTemplate

The blockTemplate configuration defines the template structure used for displaying video blocks. This configuration allows the flexibility in the structure of the block that gets copied to the Word document to align it with the block structures used in your site authoring.

Example Configuration (Video Type Assets):

The following example demonstrates how to configure the blockTemplate for video assets:

{ 
	"blockTemplate": [
 	{
   		"mimeType": "video/*",
   		"value": "<table border='1' style=\"width:100%\">\n  <tr>\n        <td style=\"background-color:#2986cc;color:#fff\">${blockName}</td>\n      </tr>\n      <tr>\n        <td>\n        <img src=\"${posterUrl}\" alt=\"${name}\">\n        <br/>\n        <a href=\"${videoUrl}\">${name}</a>\n        </td>\n      </tr>   </table>"
 	}
]
}

The above template would result in a block like this getting copied over to the Word document when the assets is pasted. As can be seen, it has the poster image and the video Url. Also the block’s header row has been custom styled.

Variables Used:
  1. blockName: Represents the name of the video block.
  2. posterUrl: Contains the URL of the image that serves as the video poster or thumbnail.
  3. name: Denotes the name of the video asset.
  4. videoUrl: Provides the public delivery URL of the video file.

filterSchema

You can set up custom search filters to make it easier to find and narrow down assets based on its metadata, such as Tags, Status, Type etc. This customization is powered by the Micro-frontend Assets Selector that allows you to search through metadata fields efficiently. For more details on how this works, see the Micro-frontend Assets Selector documentation here.

Example Configuration (Adding Tag Picker to Rail Filter Schema):
{ 
	"filterSchema": [ 
    	{ 
        	"header": "Assets Tags", 
        	"groupKey": "AssetTagsGroup", 
        	"fields": [ 
            	{ 
                	"element": "taggroup", 
                	"name": "property=metadata.application.xcm:keywords.id", 
                	"columns": 3 
            	} 
        	] 
    	} 
	] 
}

This configuration allows users to fetch Taxonomy from AEM and pick & apply Tags from that AEM Taxonomy to narrow down the assets.

Usage Note: For Delivery repository, use the name attribute’s value as property=metadata.application.xcm:keywords.id, whereas for Authors, use property=xcm:keywords.id=.

assetDomainMapping

Defines the domains mapping for respective delivery URLs to be replaced with intended values.

Example Configuration (Asset Domain mappings):
{
 	"assetDomainMapping": {
    	  "delivery-p123111-e1235123.adobeaemcloud.com":"mediapreprod.store.testdomain.com",
"delivery-p123111-e1235134.adobeaemcloud.com": "media.store.testdomain.com",
"delivery-p123111-e1235145.adobeaemcloud.com": "mediauat.store.testdomain.com"
"delivery-p123111-e1235156.adobeaemcloud.com": "mediaqa.store.testdomain.com"
 	}
}

This configuration allows users to replace any delivery domain with its corresponding CDN-mapped / custom domain. If a domain mapping doesn’t exist, the original delivery URL is retained.

Configuring the Extension Points

The customization of the Assets Sidekick Plugin is primarily driven by a configuration file. There are two options for defining this configuration file:

Option 1: Host Configuration in the Same Edge Delivery Services Project

In this option, the configuration file should be defined at the following path within your Edge Delivery Services Project:

/tools/assets-selector/config.json

Additionally, ensure that the Assets Sidekick Plugin configuration includes the following parameter set to true:

passConfig=true

Option 2: Host Configuration at Any URL and Pass It to the Assets Sidekick Plugin

Alternatively, you can host the configuration file at any accessible URL and pass it to the Assets Sidekick Plugin. In this scenario, utilize the extConfigUrl parameter to specify the URL from which the configuration will be fetched. For more information on this approach, please refer to the documentation provided.

Note: Contextual Configuration based on page being authored

The configuration can take a page’s URL as a parameter, allowing you to generate the configuration on the fly based on the page’s context. This enables the Assets Selector to use the page context when suggesting relevant assets. By doing so, you can setup configurations dynamically in the Assets Selector based on the context (the page url) passed to it, which is particularly useful for scenarios where you want your page authors to be shown only a subset of assets from your assets repository based on the context of the web page they are authoring. For e.g. show locale or region specific assets based on the locale of the page being authored.

To implement this, follow these steps:

  1. Ensure the Sidekick configuration has both passReferrer and passConfig flags set to true.
  2. Host a Configuration that can be served by the following endpoint:

https://<your-config-server>/config.json?webPath=<page-path>

Here, page-path is the URL of the page being edited in the word document, and the Assets Selector should launch in the context of that page-path. This endpoint should serve the complete configuration. It is expected that you implement the necessary server side logic at this endpoint to serve the configuration based on the provided context (the webPath) in the specified format accepted by the asset selector

For example, the endpoint can look at the webPath and return a configuration which uses the page’s tags at that webPath, to set the default tags in the Tag Picker filter of the Assets Selector. This way, the Assets Selector launches with those default tags applied, showing relevant assets based on the page's context.

Sample Configuration for Reference:

To get detailed information and a reference for configurations, please follow the readme. This guide contains sample configurations and GitHub repository references to help you adapt and deploy these configurations in your project based on your use cases and extension requirements.

Additional Considerations

In all options, ensure that the configuration URL is accessible and that Cross-Origin Resource Sharing (CORS) is enabled for the domain experience.adobe.com. If the configuration is hosted on Edge Delivery Services platform, refer to the documentation for detailed instructions on configuring CORS for hosted configurations.

The Asset Selector component leverages the micro-frontend Asset Selector, which is designed to integrate seamlessly with Sidekick. For more information, see the Micro-Frontend Asset Selector documentation.

By following these steps, you can customize the Assets Sidekick Plugin to suit your specific needs and enhance your Assets integration workflow within Adobe Experience Manager.