The aem-assets-selectors-mfe-examples from deepa02

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-wiki] (AEM CS). These components follow the [Micro Frontend architecture][microfrontend-wiki] 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.

What is this repository for
Installation
APIs
Examples
Supported Properties
Contributing
Licensing

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.

Installation

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][import-maps-wiki] 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

container (HTMLElement) — render AssetSelector into the DOM in the supplied container
props (AssetSelectorProps) — properties for the AssetSelector component. See AssetSelector Props for more details.
onRenderComplete (Function?, default: undefined) — optional callback function that is invoked when the component is rendered or updated.

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

container (HTMLElement) — render AssetSelector into the DOM in the supplied container
props (AssetSelectorProps) — properties for the AssetSelector component. See AssetSelector Props for more details.
onRenderComplete (Function?, default: undefined) — optional callback function that is invoked when the component is rendered or updated.

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

authProps (ImsAuthProps) — required properties for the ImsAuthService. See ImsAuthProps for more details.

Returns

@returns (ImsAuthService) — an instance of the ImsAuthService. See ImsAuthService for more details.

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

container (HTMLElement) — render AssetSelector into the DOM in the supplied container
props (DestinationSelectorProps) — properties for the DestinationSelector component. See DestinationSelector Props for more details.
onRenderComplete (Function?, default: undefined) — optional callback function that is invoked when the component is rendered or updated.

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

container (HTMLElement) — render DestinationSelector into the DOM in the supplied container
props (DestinationSelectorProps) — properties for the DestinationSelector component. See DestinationSelector Props for more details.
onRenderComplete (Function?, default: undefined) — optional callback function that is invoked when the component is rendered or updated.

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: 'client-id-associate-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: 'client-id-associate-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][import-maps-wiki] 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/[email protected]",
      "react-dom": "https://esm.sh/[email protected]"
    }
  }
  </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: 'client-id-associate-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/[email protected]",
      "react-dom": "https://esm.sh/[email protected]"
    }
  }
  </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: 'client-id-associate-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/[email protected]",
      "react-dom": "https://esm.sh/[email protected]"
    }
  }
</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: 'client-id-associate-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/[email protected]",
      "react-dom": "https://esm.sh/[email protected]"
    }
  }
</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: 'client-id-associate-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: 'client-id-associate-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: 'client-id-associate-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, Assets Selectors MFEs 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](./.github/CONTRIBUTING.md) for more information.

### Licensing

This project is licensed under the Apache V2 License. See [LICENSE](LICENSE) for more information.

<!-- links -->
[aem-cs-wiki]: https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/assets/home.html
[microfrontend-wiki]: https://en.wikipedia.org/wiki/Microfrontend
[import-maps-wiki]: https://github.com/WICG/import-maps

deepa02 / aem-assets-selectors-mfe-examples Goto Github PK

aem-assets-selectors-mfe-examples's Introduction

Assets Selectors

Contents

What is this repository for

Installation

APIs

PureJSSelectors.renderAssetSelector or <AssetSelector/>

Parameters

PureJSSelectors.renderAssetSelectorWithAuthFlow or <AssetSelectorWithAuthFlow />

Parameters

PureJSSelectors.registerAssetsSelectorsAuthService

Parameters

Returns

PureJSSelectors.renderDestinationSelector or <DestinationSelector/>

Parameters

PureJSSelectors.renderDestinationSelectorWithAuthFlow or <DestinationSelectorWithAuthFlow />

Parameters

Examples

Example - JavaScript

AssetSelector Usage

DestinationSelector Usage

Example - importMap via ESM CDN

AssetSelector Usage

DestinationSelector Usage

Example - React with importMap via ESM CDN

AssetSelector Usage

DestinationSelector Usage

Example - Angular

AssetSelector Usage

DestinationSelector Usage

Usage Data

aem-assets-selectors-mfe-examples's People

Contributors

Recommend Projects

Recommend Topics

Recommend Org

PureJSSelectors.`renderAssetSelector` or `<AssetSelector/>`

PureJSSelectors.`renderAssetSelectorWithAuthFlow` or `<AssetSelectorWithAuthFlow />`

PureJSSelectors.`registerAssetsSelectorsAuthService`

PureJSSelectors.`renderDestinationSelector` or `<DestinationSelector/>`

PureJSSelectors.`renderDestinationSelectorWithAuthFlow` or `<DestinationSelectorWithAuthFlow />`