Micro-Frontend Asset Selector Overview
Micro-Frontend Asset Selector provides a user interface that easily integrates with the Experience Manager Assets repository so that you can browse or search digital assets available in the repository and use them in your application authoring experience.
The Micro-Frontend user interface is made available in your application experience using the Asset Selector package. Any updates to the package are automatically imported and the latest deployed Asset Selector loads automatically within your application.
Asset Selector provides many benefits, such as:
- Ease of integration with any of the Adobe or non-Adobe applications using Vanilla JavaScript library.
- Easy to maintain as updates to the Assets Selector package are automatically deployed to the Asset Selector available for your application. There are no updates required within your application to load the latest modifications.
- Ease of customization as there are properties available that control the Asset Selector display within your application.
- Full-text search, out-of-the-box, and customized filters to quickly navigate to assets for use within the authoring experience.
- Ability to switch repositories within an IMS organization for asset selection.
- Ability to sort assets by name, dimensions, and size and view them in List, Grid, Gallery, or Waterfall view.
Prerequisites prereqs
You must ensure the following communication methods:
- The application is running on HTTPS.
- The URL of the application is in the IMS client’s allowed list of redirect URLs.
- The IMS login flow is configured and rendered using a popup on the web browser. Therefore, popups should be enabled or allowed on the target browser.
Use the above prerequisites if you require IMS authentication workflow of Asset Selector. Alternatively, if you are already authenticated with the IMS workflow, you can add the IMS information instead.
- Domain names where the integrating application is hosted.
- After provisioning, your organization will be provided with
imsClientId
,imsScope
, and aredirectUrl
corresponding to the environments requested that are essential for the configuration of Asset Selector. Without those valid properties, you cannot run the installation steps.
Installation installation
Asset Selector is available via both ESM CDN (For example, esm.sh/skypack) and UMD version.
In browsers using UMD version (recommended):
<script src="https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/assets-selectors.js"></script>
<script>
const { renderAssetSelector } = PureJSSelectors;
</script>
In browsers with import maps
support using ESM CDN version:
<script type="module">
import { AssetSelector } from 'https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/@assets/selectors/index.js'
</script>
In Deno/Webpack Module Federation using ESM CDN version:
import { AssetSelector } from 'https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/@assets/selectors/index.js'
Integrate Asset Selector using Vanilla JS integration-using-vanilla-js
You can integrate any Adobe or non-Adobe application with Experience Manager Assets repository and select assets from within the application. See Asset Selector Integration with various applications.
The integration is done by importing the Asset Selector package and connecting to the Assets as a Cloud Service using the Vanilla JavaScript library. Edit an index.html
or any appropriate file within your application to:
- Define the authentication details
- Access the Assets as a Cloud Service repository
- Configure the Asset Selector display properties
You can perform authentication without defining some of the IMS properties, if:
- You are integrating an Adobe application on Unified Shell.
- You already have an IMS token generated for authentication.
Integrate Asset Selector with various applications asset-selector-integration-with-apps
You can integrate Asset Selector with various applications such as:
Prerequisites prereqs-adobe-app
Use the following prerequisites if you are integrating Asset Selector with an Adobe application:
- Communication methods
- imsOrg
- imsToken
- apikey
Integrate Asset Selector with an Adobe application adobe-app-integration-vanilla
The following example demonstrates the usage of Asset Selector when running an Adobe application under Unified Shell or when you already have imsToken
generated for authentication.
Include the Asset Selector package in your code using the script
tag, as shown in lines 6–15 of the example below. Once the script is loaded, the PureJSSelectors
global variable is available for use. Define the Asset Selector properties as shown in lines 16–23. The imsOrg
and imsToken
properties are both required for authentication in Adobe application. The handleSelection
property is used to handle the selected assets. To render the Asset Selector, call the renderAssetSelector
function as mentioned in line 17. The Asset Selector is displayed in the <div>
container element, as shown in lines 21 and 22.
By following these steps, you can use Asset Selector with your Adobe application.
code language-html line-numbers |
---|
|
accordion | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ImsAuthProps | ||||||||||||||||||||
The
|
accordion | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ImsAuthService | ||||||||||||||
|
accordion | ||
---|---|---|
Validation with provided IMS token | ||
|
accordion | ||
---|---|---|
Register callbacks to IMS service | ||
|
Prerequisites prereqs-non-adobe-app
Use the following prerequisites if you are integrating Asset Selector with a non-Adobe application:
- Communication methods
- imsClientId
- imsScope
- redirectUrl
- imsOrg
- apikey
Asset Selector supports authentication to the Experience Manager Assets repository using Identity Management System (IMS) properties such as imsScope
or imsClientID
when you are integrating it with a non-Adobe application.
accordion |
---|
Configure Asset Selector for a non-Adobe application |
To configure Asset Selector for a non-Adobe application, you must first log a support ticket for provisioning followed by the integration steps. Logging a support ticket
|
accordion | ||
---|---|---|
Integration steps | ||
Use this example Access the Asset Selector package using the Line 14 to line 38 of the example describes the IMS flow properties, such as As you do not have an Define the authentication and other Assets as a Cloud Service access-related properties in the The Asset Selector is rendered on the
|
accordion | |||
---|---|---|---|
Unable to access delivery repository | |||
|
Prerequisites prereqs-polaris
Use the following prerequisites if you are integrating Asset Selector with Dynamic Media with OpenAPI capabilities:
-
To access Dynamic Media with OpenAPI capabilities, you must have licenses for:
- Assets repository (for example, Experience Manager Assets as a Cloud Service).
- AEM Dynamic Media.
-
Only approved assets are available for use ensuring brand consistency.
Integration for Dynamic Media with OpenAPI capabilities adobe-app-integration-polaris
Integration of Asset Selector with Dynamic Media OpenAPI process involves various steps that includes creating a customized dynamic media URL or ready to pick dynamic media URL, etc.
accordion | ||
---|---|---|
Integrate Asset Selector for Dynamic Media with OpenAPI capabilities | ||
The
This configuration allows you to view all the approved assets without folders or as a flat structure. For more information, navigate to |
accordion | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Create a Dynamic Delivery URL from approved assets | ||||||||||||||||
Once you set up Asset Selector, a schema of objects is used to create a Dynamic Delivery URL from the selected assets.
All the selected assets are carried by
Approved assets delivery API specification URL format: Where,
Approved assets delivery API The dynamic delivery URL possesses the following syntax:
|
accordion | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ready to pick dynamic delivery URL | |||||||||||||||||||
All the selected assets are carried by
Below are the two ways to traverse the JSON object:
In the above screenshot, the delivery URL of the PDF’s original rendition needs to be incorporated in the target experience if PDF is required and not its thumbnail. For example,
|
accordion |
---|
Configure custom filters |
Asset Selector for Dynamic Media with OpenAPI capabilities allows you to configure custom properties and the filters based on them. The
For the configuration, properties that are defined at For example, in Asset Selector for Dynamic Media with OpenAPI capabilities, a property on To get the name, a one-time activity must be done. Make a search API call for the asset, and get the property name (the bucket, essentially). |
Asset Selector properties asset-selector-properties
You can use the Asset Selector properties to customize the way the Asset Selector is rendered. The following table lists the properties that you can use to customize and use the Asset Selector.
true
, Asset Selector is rendered in a left rail view. If it is marked false
, the Asset Selector is rendered in modal view.imsOrg
key is required to authenticate whether the organization you are accessing is under Adobe IMS or not.imsToken
is required if you are using an Adobe application for the integration.apiKey
is required if you are using an Adobe application integration.<Object>
[{id: 'urn:234}, {id: 'urn:555'}]
An asset must be available in the current directory. If you need to use a different directory, provide a value for the path
property as well.rail
property to enable rail view of assets viewer.Object<{ id?: string, defaultMessage?: string, description?: string}>
i18nSymbols
prop. Passing a value through this interface overrides the default translations provided and instead use your own. To perform the override, you must pass a valid Message Descriptor object to the key of i18nSymbols
that you want to override.intl.locale
prop. For example: intl={{ locale: "es-es" }}
The locale strings supported follow the ISO 639 - Codes for the representation of names of languages standards.
List of supported locales: English - ‘en-us’ (default) Spanish - ‘es-es’ German - ‘de-de’ French - ‘fr-fr’ Italian - ‘it-it’ Japanese - ‘ja-jp’ Korean - ‘ko-kr’ Portuguese - ‘pt-br’ Chinese (Traditional) - ‘zh-cn’ Chinese (Taiwan) - ‘zh-tw’
Array<string>
{allowList?: Object}
light
or dark
) for the Asset Selector.Invoked with array of Asset items when assets are selected and the Select
button on the modal is clicked. This function is only invoked in modal view. For rail view, use the handleAssetSelection
or onDrop
functions. Example:
handleSelection=(assets: Asset[])=> {…}
See Selected Asset Type for details.
Invoked with array of items as the assets are being selected or unselected. This is useful when you want to listen for assets as user selects them. Example:
handleSelection=(assets: Asset[])=> {…}
See Selected Asset Type for details.
Close
button in modal view is pressed. This is only called in modal
view and disregarded in rail
view.single
or multiple
selection of assets at a time.Syntax:
aemTierType:[0]: "author" 1: "delivery"
For example, if both
["author","delivery"]
are used, then the repository switcher displays options for both author and delivery.filterRepoList
callback function that calls Experience Manager repository and returns a filtered list of repositories.EXPIRED
, EXPIRING_SOON
or NOT_EXPIRED
based on the expiry date of an asset that you provide. See customize expired assets. Additionally, you can use allowSelectionAndDrag in which the value of the function can either be true
or false
. When the value is set to false
, the expired asset cannot be selected or dragged on the canvas.Examples to use Asset Selector properties usage-examples
You can define the Asset Selector properties in the index.html
file to customize the Asset Selector display within your application.
Example 1: Asset Selector in rail view
If the value of the AssetSelector rail
is set to false
or is not mentioned in the properties, Asset Selector displays in the Modal view by default. The acvConfig
property allows for some in-depth configurations, like the Drag and Drop. Visit enable or disable drag and drop to understand the usage of acvConfig
property.
Example 2: Metadata popover
Use various properties to define metadata of an asset that you want to view using an info icon. The info popover provides the collection of information about asset or the folder including title, dimensions, date of modification, location, and description of an asset. In the example below, various properties are used to display metadata of an asset, for example, repo:path
property specifies the location of an asset.
Example 3: Custom filter property in rail view
In addition to the faceted search, Assets Selector lets you customize various attributes to refine your search from Adobe Experience Manager as a Cloud Service application. Add the following code to add customized search filters in your application. In the example below, the Type Filter
search that filters the asset type among Images, Documents, or Videos or the filter type that you have added for the search.
Functional setup code snippets code-snippets
Define the prerequisites in the index.html
file or a similar file within your application implementation to define the authentication details to access the Experience Manager Assets repository. Once done, you can add code snippets as per your requirement.
Customize filter panel customize-filter-panel
You can add the following code snippet in assetSelectorProps
object to customize the filter panel:
filterSchema: [
{
header: 'File Type',
groupKey: 'TopGroup',
fields: [
{
element: 'checkbox',
name: 'type',
options: [
{
label: 'Images',
value: '<comma separated mimetypes, without space, that denote all images, for e.g., image/>',
},
{
label: 'Videos',
value: '<comma separated mimetypes, without space, that denote all videos for e.g., video/,model/vnd.mts,application/mxf>'
}
]
}
]
},
{
fields: [
{
element: 'checkbox',
name: 'type',
options: [
{ label: 'JPG', value: 'image/jpeg' },
{ label: 'PNG', value: 'image/png' },
{ label: 'TIFF', value: 'image/tiff' },
{ label: 'GIF', value: 'image/gif' },
{ label: 'MP4', value: 'video/mp4' }
],
columns: 3,
},
],
header: 'Mime Types',
groupKey: 'MimeTypeGroup',
}},
{
fields: [
{
element: 'checkbox',
name: 'property=metadata.application.xcm:keywords.value',
options: [
{ label: 'Fruits', value: 'fruits' },
{ label: 'Vegetables', value: 'vegetables'}
],
columns: 3,
},
],
header: 'Food Category',
groupKey: 'FoodCategoryGroup',
}
],
Customize information in modal view customize-info-in-modal-view
You can customize the details view of an asset when you click the
// Create an object infoPopoverMap and set the property `infoPopoverMap` with it in assetSelectorProps
const infoPopoverMap = (map) => {
// for example, to skip `path` from the info popover view
let defaultPopoverData = PureJSSelectors.getDefaultInfoPopoverData(map);
return defaultPopoverData.filter((i) => i.label !== 'Path'
};
assetSelectorProps.infoPopoverMap = infoPopoverMap;
Enable or disable drag and drop mode enable-disable-drag-and-drop
Add the following properties to assetSelectorProp
to enable drag and drop mode. To disable drag and drop, replace the true
parameter with false
.
rail: true,
acvConfig: {
dragOptions: {
allowList: {
'*': true,
},
},
selectionType: 'multiple'
}
// the drop handler to be implemented
function drop(e) {
e.preventDefault();
// following helps you get the selected assets – an array of objects.
const data = JSON.parse(e.dataTransfer.getData('collectionviewdata'));
}
Selection of Assets selection-of-assets
Selected Asset Type is an array of objects that contains the asset information when using the handleSelection
, handleAssetSelection
, and onDrop
functions.
Execute the following steps to configure the selection of single or multiple assets:
acvConfig: {
selectionType: 'multiple' // 'single' for single selection
}
// the `handleSelection` callback, always gets you the array of selected assets
Schema Syntax
interface SelectedAsset {
'repo:id': string;
'repo:name': string;
'repo:path': string;
'repo:size': number;
'repo:createdBy': string;
'repo:createDate': string;
'repo:modifiedBy': string;
'repo:modifyDate': string;
'dc:format': string;
'tiff:imageWidth': number;
'tiff:imageLength': number;
'repo:state': string;
computedMetadata: Record<string, any>;
_links: {
'https://ns.adobe.com/adobecloud/rel/rendition': Array<{
href: string;
type: string;
'repo:size': number;
width: number;
height: number;
[others: string]: any;
}>;
};
}
The following table describes some of the important properties of the Selected Asset object.
Array<string>
Record<string, any>
Record<string, any>
Array<Object>
Customize expired assets customize-expired-assets
Asset Selector allows you to control the usage of an expired asset. You can customize the expired asset with an Expiring soon badge that can help you know in advance about the assets that are going to expire within 30 days from the current date. Moreover, this can be customized as per the requirement. You can also allow the selection of an expired asset on the canvas or vice versa. The customization of an expired asset can be done using some code snippets in various ways:
expiryOptions: {
getExpiryStatus: getExpiryStatus;
}
Selection of an expired asset selection-of-expired-asset
You can customize the usage of an expired asset to make it either selectable or unselectable. You can customize whether you want to allow the drag and drop of an expired asset on the Asset Selector canvas or not. To do this, use the following parameters to make an asset unselectable on the canvas:
expiryOptions:{
allowSelectionAndDrop: false;
}
Setting duration of an expired asset set-duration-of-expired-asset
The following code snippet helps you set Expiring Soon badge for the assets that are expiring within next five days:
/**
const getExpiryStatus = async (asset) => {
if (!asset.expirationDate) {
return null;
}
const currentDate = new Date();
const millisecondsInDay = 1000 * 60 * 60 * 24;
const fiveDaysFromNow = new Date(value: currentDate.getTime() + 5 * millisecondsInDay);
const expirationDate = new Date(asset.expirationDate);
if (expirationDate.getTime() < currentDate.getTime()) {
return 'EXPIRED';
} else if (expirationDate.getTime() < fiveDaysFromNow.getTime()) {
return 'EXPIRING_SOON';
} else {
return 'NOT_EXPIRED';
}
};
Refer to the following example to understand how the property works to fetch the current date and time:
const currentData = new Date();
currentData.getTime(),
returns 1718779013959
which is as per the date format 2024-06-19T06:36:53.959Z.
Customize toast message of an expired asset customize-toast-message
The showToast
property is used to customize the toast message that you want to show on an expired asset.
Syntax:
{
type: 'ERROR', 'NEUTRAL', 'INFO', 'SUCCESS',
message: '<message to be shown>',
timeout: optional,
}
The default timeout is 500 milliseconds. Whereas, you can modify it as per the requirement. Additionally, passing the value timeout: 0
keeps the toast open until you click on the cross button.
Below is an example to show a toast message when it is required to disallow selection for a folder and show a corresponding message:
const showToast = {
type: 'ERROR',
message: 'Folder cannot be selected',
timeout: 5000,
}
Use the following code snippet to show toast message for the usage of an expired asset:
Contextual invocation filter contextual-invocation-filter
Asset Selector allows you to add a tag picker filter. It supports a tag group which combines all the relevant tags to a particular tagging group. Additionally, it allows you to select additional tags corresponding to the asset that you are looking for. Moreover, you can also set the default tag groups under the contextual invocation filter that are mostly used by you so that they are accessible to you on the go.
![NOTE]
- You need to add contextual invocation code snippet to enable tagging filter in the search.
- It is mandatory to use name property corresponding to the tag group type
(property=xcm:keywords.id=)
.
Syntax:
const filterSchema=useMemo(() => {
return: [
{
element: 'taggroup',
name: 'property=xcm:keywords.id='
},
];
}, []);
To add tag groups in the filters panel, it is mandatory to add at least one tag group as default. Additionally, use the below code snippet to add the default tags that are pre-selected from the tag group.
export const WithAssetTags = (props) = {
const [selectedTags, setSelectedTags] = useState (
new Set(['orientation', 'color', 'facebook', 'experience-fragments:', 'dam', 'monochrome'])
const handleSelectTags = (selected) => {
setSelectedTags (new Set (selected)) ;
};
const filterSchema = useMemo ((); => {
return {
schema: [
{
fields: [
{
element: 'checkbox',
name: 'property=xcm:keywords=',
defaultValue: Array. from(selectedTags),
options: assetTags,
orientation: 'vertical',
},
],
header: 'Asset Tags',
groupkey: 'AssetTagsGroup',
],
},
};
}, [selectedTags]);
Handling selection of Assets using Object Schema handling-selection
The handleSelection
property is used to handle single or multiple selections of Assets in Assets Selector. The example below states the syntax of usage of handleSelection
.
Disabling selection of Assets disable-selection
Disable selection is used to hide or disable the assets or folders from being selectable. It hides the select checkbox from the card or asset which refrains it from getting selected. To use this feature, you can declare the position of an asset or folder that you want to disable in an array. For example, if you want to disable the selection of a folder appearing at first position, you can add the following code:disableSelection: [0]:folder
You can provide the array with a list of mime types (such as image, folder, file, or other mime types for example, image/jpeg) that you want to disable. The mime types that you declare are mapped into data-card-type
and data-card-mimetype
attributes of an asset.
Additionally, Assets with disabled selection are draggable. To disable drag and drop of a particular asset type, you can use dragOptions.allowList
property.
The syntax of disable selection is as follows:
(args)=> {
return(
<ASDialogWrapper
{...args}
disableSelection={args.disableSelection}
handleAssetSelection={action('handleAssetSelection')}
handleSelection={action('handleSelection')}
selectionType={args.selectionType}
/>
);
}
Using Asset Selector using-asset-selector
Once the Asset Selector is set up and you are authenticated to use Asset Selector with your Adobe Experience Manager as a Cloud Service application, you can select assets or perform various other operations to search for your assets within the repository.
- A: Hide/Show panel
- B: Repository switcher
- C: Assets
- D: Filters
- E: Search bar
- F: Sorting
- G: Sorting in ascending or descending order
- H: View
Hide/Show panel hide-show-panel
To hide folders in the left navigation, click Hide folders icon. To undo the changes, click the Hide folders icon again.
Repository switcher repository-switcher
Asset Selector also lets you switch repositories for asset selection. You can select the repository of your choice from the drop-down available in the left panel. The repository options available in the drop-down list are based on the repositoryId
property defined in the index.html
file. It is based on the environment from the selected IMS org that is accessed by the logged in user. Consumers can pass a preferred repositoryID
and in that case the Asset Selector stops rendering the repo switcher and render assets from the given repository only.
Assets repository
It is a collection of assets folders that you can use to perform operations.
Out-of-the-box filters filters
Asset Selector also provides out-of-the-box filter options to refine your search results. The following filters are available:
-
Status: includes the current state of asset among
all
,approved
,rejected
, orno status
. -
File type: includes
folder
,file
,images
,documents
, orvideo
. -
Expiration status: mentions the assets based upon its expiration duration. You can either check the
Expired
checkbox to filter assets that are expired; or setExpiration Duration
of an asset to display assets based on their expiry duration. When an asset is expired already or is near to expire, a badge appears depicting the same. Moreover, you can control whether you want to allow usage (or drag and drop) of an expired asset. See more about customize expired assets. By default, the Expiring Soon badge is displayed for assets that are expiring in next 30 days. However, you can configure the expiration usingexpirationDate
property.note tip TIP If you want to view or filter assets based on their future expiry date, mention the future date range in the Expiration Duration
field. It displays the assets with expiring soon badge on them. -
MIME type: includes
JPG
,GIF
,PPTX
,PNG
,MP4
,DOCX
,TIFF
,PDF
,XLSX
. -
Image Size: includes minimum/maximum width, minimum/maximum height of image.
Custom search
Apart from the full-text search, Asset Selector lets you search assets within files using customized search. You can use custom search filters in both Modal view and Rail view modes.
You can also create default search filter to save the fields that you frequently search for and use them later. To create custom search for your assets, you can use filterSchema
property.
Search bar search-bar
Asset Selector lets you perform full text search of assets within the selected repository. For example, if you type the keyword wave
in the search bar, all the assets with the wave
keyword mentioned in any of the metadata properties are displayed.
Sorting sorting
You can sort assets in Asset Selector by name, dimensions, or size of an asset. You can also sort the assets in ascending or descending order.
Types of view types-of-view
Asset Selector lets you view the asset in four different views: