search

adobe / aem-assets-selectors-mfe-examples

Assets Selectors contains a collection of components such as AssetSelector and DestinationSelector from Adobe Experience Manager Assets as a Cloud Service (AEM CS)
Apache License 2.0
4 stars 7 forks source link

readme

Assets Selectors

Assets Selectors contains a collection of components such as AssetSelector and DestinationSelector from Adobe Experience Manager Assets as a Cloud Service (AEM CS). These components follow the Micro Frontend architecture and are consumable in your application via convenient JavaScript APIs to search, browse, and retrieve digital assets available in the AEM CS repository.

The AssetSelector component allows you to select and retrieve assets, while the DestinationSelector component enables you to choose a destination to save or move assets to.

Contents

What is this repository for

This GitHub repository contains usage examples for the Assets Selectors' JavaScript APIs in various frameworks/libraries, including Vanilla JavaScript, React, Angular, and others. The JavaScript APIs enable you to conveniently integrate Adobe AEM CS assets into your application and support functions such as searching, browsing, retrieving assets and their metadata, renditions, and more.

assets-selectors-high-level-flow

Installation

:warning: This repository is intended to serve as a supplemental documentation describing the available APIs and usage examples for integrating Assets Selectors. Before attempting to install or use the Assets Selectors, ensure that your organization has been provisioned to access the Assets Selectors as part of the AEM Assets as a Cloud Service (CS) profile. If you have not been provisioned, you will not be able to successfully integrate or use these components. To request provisioning, your program admin should raise a support ticket marked as P2 from Admin Console and include the following information:

After provisioning, your organization will be provided with an imsClientId, imsScope, and a redirectUrl corresponding to the environment that you request —which are essential for the configuration of Assets Selectors to work end-to-end. Without those valid properties, you will not be able to integrate with Assets Selectors.

Assets Selectors is available via both ESM CDN (think esm.sh/skypack) and UMD version.

In browsers using UMD version:

<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 importMap 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'

APIs

This package exports the global identifier PureJSSelectors when installed via UMD and named exports PureJSSelectors, AssetSelector, AssetSelectorWithAuthFlow, DestinationSelector, DestinationSelectorWithAuthFlow, registerAssetsSelectorsAuthService when installed via ESM. There are no default exports.

Below are the API description exported by this package in identifier PureJSSelectors and its equivalent JSX components that are available via ESM imports.

PureJSSelectors.renderAssetSelector or <AssetSelector/>

Renders the AssetSelector component on the provided container element and accepts all of the properties described in the AssetSelector Props.

This method assumes that you supply a valid imsToken that you could have obtained using ImsAuthService.getImsToken() or another medium. If you do not have an imsToken, you can use renderAssetSelectorWithAuthFlow which implements an authentication flow to obtain a user based imsToken.

Parameters
PureJSSelectors.renderAssetSelector(container: HTMLElement, props: AssetSelectorProps, onRenderComplete?: Function): void

// JSX

<AssetSelector {...props} />

PureJSSelectors.renderAssetSelectorWithAuthFlow or <AssetSelectorWithAuthFlow />

Renders the AssetSelector component on the provided container element and accepts all of the properties described in the AssetSelector Props. The AssetSelectorWithAuthFlow component extends the AssetSelector component to include an authentication flow. When there's no imsToken present, the AssetSelectorWithAuthFlow component will show a Adobe login flow to obtain the imsToken and then render the AssetSelector component.

It is recommended that you call registerAssetsSelectorsAuthService on your page load before calling renderAssetSelectorWithAuthFlow or <AssetSelectorWithAuthFlow/>. In the event where you cannot call registerAssetsSelectorsAuthService, you can supply ImsAuthProps along with AssetSelectorProps. However, that might not create a great user experience.

Parameters
PureJSSelectors.renderAssetSelectorWithAuthFlow(container: HTMLElement, props: AssetSelectorProps, onRenderComplete?: Function): void

// JSX

<AssetSelectorWithAuthFlow {...props} />

PureJSSelectors.registerAssetsSelectorsAuthService

Instantiates the ImsAuthService process. This process registers the authorization service for your AEM CS Assets repository and subscribes to authorization flow events.

It is recommended that you call this function on your application page load. You must also call this function if you're using the AssetSelectorWithAuthFlow or DestinationSelectorWithAuthFlow components. This API is not required if you're using the AssetSelector or DestinationSelector components and already obtained a valid imsToken.

Parameters
Returns
PureJSSelectors.registerAssetsSelectorsAuthService(authProps: ImsAuthProps): ImsAuthService

PureJSSelectors.renderDestinationSelector or <DestinationSelector/>

Renders the DestinationSelector component on the provided container element and accepts all of the properties described in the DestinationSelector Props.

This method assumes that you supply a valid imsToken that you could have obtained using ImsAuthService.getImsToken() or another medium. If you do not have an imsToken, you can use renderDestinationSelectorWithAuthFlow which implements an authentication flow to obtain a user based imsToken.

Parameters
PureJSSelectors.renderDestinationSelector(container: HTMLElement, props: DestinationSelectorProps, onRenderComplete?: Function): void

PureJSSelectors.renderDestinationSelectorWithAuthFlow or <DestinationSelectorWithAuthFlow />

Renders the DestinationSelector component on the provided container element and accepts all of the properties described in the DestinationSelector Props. The DestinationSelectorWithAuthFlow component extends the DestinationSelector component to include an authentication flow. When there's no imsToken present, the DestinationSelectorWithAuthFlow component will show a Adobe login flow to obtain the imsToken and then render the DestinationSelector component.

It is recommended that you call registerAssetsSelectorsAuthService on your page load before calling renderDestinationSelectorWithAuthFlow or <DestinationSelectorWithAuthFlow/>. In the event where you cannot call registerAssetsSelectorsAuthService, you can supply ImsAuthProps along with DestinationSelectorProps. However, that might not create a great user experience.

Parameters
PureJSSelectors.renderDestinationSelectorWithAuthFlow(container: HTMLElement, props: DestinationSelectorProps, onRenderComplete?: Function): void

Examples

Assets Selectors allows you to integrate the AssetSelector and DestinationSelector components into your application using vanilla JavaScript, React, and other frameworks. Below, are some examples of how you can make use of AssetSelector component into your application.

Example - JavaScript

Assets Selectors UMD version exposes a global variable PureJSSelectors which exposes the Asset Selector and Destination Selector APIs. Below is an example of how you can use the Asset Selector and Destination Selector components in your application using the built in auth flow. For a more complete and runnable code, refer to the Vanilla JavaScript demo

AssetSelector Usage

// 1. Include the CDN link in your script tag
<script src="https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/assets-selectors.js"></script>

// 2. Register the Assets Selectors Auth Service on document load
// Note: it is recommended that you call registerAssetsSelectorsAuthService before you call renderAssetSelectorWithAuthFlow
PureJSSelectors.registerAssetsSelectorsAuthService({
    imsClientId: '<IMS_CLIENT_ID_ASSOCIATED_WITH_YOUR_AEM_ASSETS_REPOSITORY>',
    imsScope: 'additional_info.projectedProductContext,openid',
    redirectUri: window.location.href
});

// 3. Render the AssetSelector component with built in auth flow
const props = {
    imsOrg: "your-aem-assets-repository-ims-org",
    handleSelection: (assets) => {
        ...
    }
}

PureJSSelectors.renderAssetSelectorWithAuthFlow(document.getElementById('asset-selector-container'), props);

DestinationSelector Usage

// 1. Include the CDN link in your script tag
<script src="https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/assets-selectors.js"></script>

// 2. Register the Assets Selectors Auth Service on document load
// Note: it is recommended that you call registerAssetsSelectorsAuthService before you call renderDestinationSelectorWithAuthFlow
PureJSSelectors.registerAssetsSelectorsAuthService({
    imsClientId: '<IMS_CLIENT_ID_ASSOCIATED_WITH_YOUR_AEM_ASSETS_REPOSITORY>',
    imsScope: 'additional_info.projectedProductContext,openid',
    redirectUri: window.location.href
});

// 3. Render the DestinationSelector component with built in auth flow
const props = {
    imsOrg: "your-aem-assets-repository-ims-org",
    onConfirm: (selectedDestination) => {
        ...
    }
}

PureJSSelectors.renderDestinationSelectorWithAuthFlow(document.getElementById('destination-selector-container'), props);
<!-- In your HTML file where AssetSelector or DestinationSelector will be rendered on to the container element -->
<div id="asset-selector-container"></div>
<div id="destination-selector-container"></div>

Example - importMap via ESM CDN

Assets Selectors ESM CDN version exposes PureJSSelectors as a named export. As well as React JSX components for Asset Selector and Destination Selector APIs. It takes advantage of the browser's new importMap feature. This feature allows you to define a mapping of import names to URLs. This is similar to how you would use a package manager like npm or yarn, but without the need for a build step.

Note: if your project does not have React as a dependency, you will need to include React and ReactDOM in your importMap.

AssetSelector Usage

// 1. Supply the browser with importMap specifier
<script type="importmap">
  {
    "imports": {
      "@assets/selectors": "https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/@assets/selectors/index.js",
      "react": "https://esm.sh/react@18.2.0",
      "react-dom": "https://esm.sh/react-dom@18.2.0"
    }
  }
  </script>

<script type="module">
  // 2. Import the Assets Selectors components from the alias
  import { registerAssetsSelectorsAuthService, renderAssetSelectorWithAuthFlow } from '@assets/selectors';

  // 3. Register the Assets Selectors Auth Service
  // Note: it is recommended that you call registerAssetsSelectorsAuthService before you call renderAssetSelectorWithAuthFlow
  registerAssetsSelectorsAuthService({
      imsClientId: '<IMS_CLIENT_ID_ASSOCIATED_WITH_YOUR_AEM_ASSETS_REPOSITORY>',
      imsScope: 'additional_info.projectedProductContext,openid',
      redirectUri: window.location.href
  });

  // 4. Render the AssetSelector component with built in auth flow
  const props = {
      imsOrg: "your-aem-assets-repository-ims-org",
      handleSelection: (assets) => {
          ...
      }
  }
  renderAssetSelectorWithAuthFlow(document.getElementById('asset-selector-container'), props);

</script>

DestinationSelector Usage

// 1. Supply the browser with importMap specifier
<script type="importmap">
  {
    "imports": {
      "@assets/selectors": "https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/@assets/selectors/index.js",
      "react": "https://esm.sh/react@18.2.0",
      "react-dom": "https://esm.sh/react-dom@18.2.0"
    }
  }
  </script>

<script type="module">
  // 2. Import the Assets Selectors components from the alias
  import { registerAssetsSelectorsAuthService, renderDestinationSelectorWithAuthFlow } from '@assets/selectors';

  // 3. Register the Assets Selectors Auth Service
  // Note: it is recommended that you call registerAssetsSelectorsAuthService before you call renderDestinationSelectorWithAuthFlow
  registerAssetsSelectorsAuthService({
      imsClientId: '<IMS_CLIENT_ID_ASSOCIATED_WITH_YOUR_AEM_ASSETS_REPOSITORY>',
      imsScope: 'additional_info.projectedProductContext,openid',
      redirectUri: window.location.href
  });

  // 4. Render the DestinationSelector component with built in auth flow
  const props = {
      imsOrg: "your-aem-assets-repository-ims-org",
      onConfirm: (selectedDestination) => {
          ...
      }
  }
  renderDestinationSelectorWithAuthFlow(document.getElementById('destination-selector-container'), props);

</script>

Example - React with importMap via ESM CDN

Assets Selectors ESM CDN version also exposes AssetSelector, AssetSelectorWithAuthFlow, DestinationSelector, DestinationSelectorWithAuthFlow and registerAssetsSelectorsAuthService React JSX components.

Note: if your project does not have React as a dependency, you will need to include React and ReactDOM in your importMap. For a more complete and runnable code, refer to the React demo

AssetSelector Usage

// 1. Supply the browser with importMap specifier
<script type="importmap">
  {
    "imports": {
      "@assets/selectors": "https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/@assets/selectors/index.js",
      "react": "https://esm.sh/react@18.2.0",
      "react-dom": "https://esm.sh/react-dom@18.2.0"
    }
  }
</script>

<script type="module">
  import React, { useEffect } from 'react';
  import { createRoot } from 'react-dom/client';

  // 2. Import the Assets Selectors components from the alias
  import { AssetSelectorWithAuthFlow, registerAssetsSelectorsAuthService } from '@assets/selectors';

  const App = () => {
    // 3. Register the Assets Selectors Auth Service on component load
    // Note: it is recommended that you call registerAssetsSelectorsAuthService before rendering AssetSelectorWithAuthFlow

    const imsAuthProps = {
        imsClientId: '<IMS_CLIENT_ID_ASSOCIATED_WITH_YOUR_AEM_ASSETS_REPOSITORY>',
        imsScope: 'additional_info.projectedProductContext,openid',
        redirectUri: window.location.href
    };

    useEffect(() => {
        registerAssetsSelectorsAuthService(imsAuthProps);
    }, []);

    // 4. Return and render the AssetSelector component with built in auth flow
    const props = {
        imsOrg: "your-aem-assets-repository-ims-org",
        handleSelection: (assets) => {
            ...
        }
    }

    return <AssetSelectorWithAuthFlow {...props} />;
}

const root = createRoot(document.getElementById('root'));
root.render(<App />);

</script>

DestinationSelector Usage

// 1. Supply the browser with importMap specifier
<script type="importmap">
  {
    "imports": {
      "@assets/selectors": "https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/@assets/selectors/index.js",
      "react": "https://esm.sh/react@18.2.0",
      "react-dom": "https://esm.sh/react-dom@18.2.0"
    }
  }
</script>

<script type="module">
  import React, { useEffect } from 'react';
  import { createRoot } from 'react-dom/client';

  // 2. Import the Assets Selectors components from the alias
  import { DestinationSelectorWithAuthFlow, registerAssetsSelectorsAuthService } from '@assets/selectors';

  const App = () => {
    // 3. Register the Assets Selectors Auth Service on component load
    // Note: it is recommended that you call registerAssetsSelectorsAuthService before rendering DestinationSelectorWithAuthFlow

    const imsAuthProps = {
        imsClientId: '<IMS_CLIENT_ID_ASSOCIATED_WITH_YOUR_AEM_ASSETS_REPOSITORY>',
        imsScope: 'additional_info.projectedProductContext,openid',
        redirectUri: window.location.href
    };

    useEffect(() => {
        registerAssetsSelectorsAuthService(imsAuthProps);
    }, []);

    // 4. Return and render the DestinationSelector component with built in auth flow
    const props = {
        imsOrg: "your-aem-assets-repository-ims-org",
        onConfirm: (selectedDestination) => {
            ...
        }
    }

    return <DestinationSelectorWithAuthFlow {...props} />;
}

const root = createRoot(document.getElementById('root'));
root.render(<App />);

</script>

Example - Angular

You can use the Assets Selectors ESM CDN/UMD version in your Angular application. The following example shows how to use the Assets Selectors in Angular.

Note: Assets Selectors depend on React you must resolve React as a dependency, before you can use the Assets Selectors in your Angular application. For a more complete and runnable code, refer to the Angular demo

AssetSelector Usage

// 1. Include the CDN link in your index.html script tag
<script src="https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/assets-selectors.js"></script>

// component code
@Component({
  selector: 'asset-selector',
  template: '<div id="asset-selector"></div>'
})

export class AssetSelectorComponent implements OnInit, AfterViewInit {
  ngOnInit() {
      // 2. Register the Assets Selectors Auth Service on component load
      // Note: it is recommended that you call registerAssetsSelectorsAuthService before calling renderAssetSelectorWithAuthFlow

      const imsAuthProps = {
          imsClientId: '<IMS_CLIENT_ID_ASSOCIATED_WITH_YOUR_AEM_ASSETS_REPOSITORY>',
          imsScope: 'additional_info.projectedProductContext,openid',
          redirectUri: window.location.href
      };
      PureJSSelectors.registerAssetsSelectorsAuthService(imsAuthProps);   
  }

  ngAfterViewInit() {
      // 3. Render the AssetSelector component with built in auth flow
      const props = {
          imsOrg: "your-aem-assets-repository-ims-org",
          handleSelection: (assets) => {
              ...
          }
      }
      PureJSSelectors.renderAssetSelectorWithAuthFlow(document.getElementById('asset-selector'), props);
  }
}

DestinationSelector Usage

// 1. Include the CDN link in your index.html script tag
<script src="https://experience.adobe.com/solutions/CQ-assets-selectors/static-assets/resources/assets-selectors.js"></script>

// component code
@Component({
  selector: 'destination-selector',
  template: '<div id="destination-selector"></div>'
})

export class AssetSelectorComponent implements OnInit, AfterViewInit {
  ngOnInit() {
      // 2. Register the Assets Selectors Auth Service on component load
      // Note: it is recommended that you call registerAssetsSelectorsAuthService before calling renderDestinationSelectorWithAuthFlow

      const imsAuthProps = {
          imsClientId: '<IMS_CLIENT_ID_ASSOCIATED_WITH_YOUR_AEM_ASSETS_REPOSITORY>',
          imsScope: 'additional_info.projectedProductContext,openid',
          redirectUri: window.location.href
      };
      PureJSSelectors.registerAssetsSelectorsAuthService(imsAuthProps);   
  }

  ngAfterViewInit() {
      // 3. Render the DestinationSelector component with built in auth flow
      const props = {
          imsOrg: "your-aem-assets-repository-ims-org",
          onConfirm: (selectedDestination) => {
              ...
          }
      }
      PureJSSelectors.renderDestinationSelectorWithAuthFlow(document.getElementById('destination-selector'), props);
  }
}
// In your template, AssetSelector/DestinationSelector will be rendered anywhere you're using this selector
<asset-selector></asset-selector>
<destination-selector></destination-selector>


Usage Data

By default, AssetsSelectors collect usage data to help improve the product. If you wish to opt out of any usage data collection, you can do so by setting the disableTracking property to true in the AssetSelectorProps or DestinationSelectorProps.

Contributing

Contributions are welcomed! Read the Contributing Guide for more information.

Licensing

This project is licensed under the Apache V2 License. See LICENSE for more information.