diff --git a/src/pages/config.md b/src/pages/config.md index b6bf9ce6..87776f79 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -11,6 +11,7 @@ - [Universal Editor](/services/aem-universal-editor/index.md) - [Adobe Commerce Admin](https://developer.adobe.com/commerce/extensibility/admin-ui-sdk/) - [AEM Assets View](/services/aem-assets-view/index.md) + - [AEM Assets Content Hub](/services/aem-assets-content-hub/index.md) - [AEM Experience Hub](/services/aem-experience-hub/index.md) - [Extension Manager](/extension-manager/index.md) @@ -56,6 +57,11 @@ - [Step-by-step Extension Development](/services/aem-assets-view/extension-development/index.md) - [Code Generation](/services/aem-assets-view/code-generation/index.md) - [Troubleshooting](/services/aem-assets-view/debug/index.md) + - [AEM Experience Hub](/services/aem-experience-hub/index.md) + - [Extension Points](/services/aem-experience-hub/api/index.md) + - [Common Concepts](/services/aem-experience-hub/api/commons/index.md) + - [Dashboard](/services/aem-experience-hub/api/dashboard/index.md) + - [Step-by-step Extension Development](/services/aem-experience-hub/extension-development/index.md) - [Extension Manager](/extension-manager/index.md) - [Feature Highlights](/extension-manager/feature-highlights/index.md) - [Extensions Developed By Adobe](/extension-manager/extension-developed-by-adobe/index.md) @@ -74,8 +80,12 @@ - [Working with events](/services/aem-universal-editor/api/events/index.md) - [Retrieving Data from the Universal Editor](/services/aem-universal-editor/api/data/index.md) - [Triggering Universal Editor actions from the extension](/services/aem-universal-editor/api/actions/index.md) - - [AEM Experience Hub](/services/aem-experience-hub/index.md) - - [Extension Points](/services/aem-experience-hub/api/index.md) - - [Common Concepts](/services/aem-experience-hub/api/commons/index.md) - - [Dashboard](/services/aem-experience-hub/api/dashboard/index.md) - - [Step-by-step Extension Development](/services/aem-experience-hub/extension-development/index.md) + - [AEM Assets Content Hub](/services/aem-assets-content-hub/index.md) + - [Extension Point](/services/aem-assets-content-hub/api/index.md) + - [Common Concepts](/services/aem-assets-content-hub/api/commons/index.md) + - [Asset Details](/services/aem-assets-content-hub/api/asset-details/index.md) + - [Card Actions](/services/aem-assets-content-hub/api/card-actions/index.md) + - [Selection Bar](/services/aem-assets-content-hub/api/selection-bar/index.md) + - [Step-by-Step Extension Development](/services/aem-assets-content-hub/extension-development/index.md) + - [Code Generation](/services/aem-assets-content-hub/code-generation/index.md) + - [Troubleshooting](/services/aem-assets-content-hub/debug/index.md) diff --git a/src/pages/index.md b/src/pages/index.md index 1a6a96c4..66e0a4b8 100644 --- a/src/pages/index.md +++ b/src/pages/index.md @@ -118,6 +118,12 @@ Start building extensions for Adobe Commerce Admin Start building extensions for AEM Assets View (Assets Ultimate only) + + +[AEM Assets Content Hub](services/aem-assets-content-hub/index.md) + +Customize Content Hub workflows with asset details, card, and selection bar extensions + ## Experiment diff --git a/src/pages/services/aem-assets-content-hub/api/asset-details/asset-details.webp b/src/pages/services/aem-assets-content-hub/api/asset-details/asset-details.webp new file mode 100644 index 00000000..48b81d89 Binary files /dev/null and b/src/pages/services/aem-assets-content-hub/api/asset-details/asset-details.webp differ diff --git a/src/pages/services/aem-assets-content-hub/api/asset-details/index.md b/src/pages/services/aem-assets-content-hub/api/asset-details/index.md new file mode 100644 index 00000000..885c989f --- /dev/null +++ b/src/pages/services/aem-assets-content-hub/api/asset-details/index.md @@ -0,0 +1,174 @@ +--- +title: Asset Details - AEM Assets Content Hub Extensibility +description: Add a custom panel to the AEM Assets Content Hub Asset Details interface. +contributors: + - https://github.com/AdobeDocs/uix +--- + +# Asset Details + +The Asset Details interface in AEM Assets Content Hub shows detailed information about the selected asset. + +Extensions should use the unified `aem/assets/contenthub/1` extension point to customize Asset Details. Asset Details capabilities are provided through the `assetDetails` namespace described below. + +## Custom panels + +The extensibility feature allows adding new panels and corresponding icon buttons to the Asset Details side rail using the [`assetDetails`](#assetdetails-namespace) namespace. Custom icons appear with the standard panel icons. + +![Asset Details in AEM Assets Content Hub](asset-details.webp) + +The host application fully manages UI interactions, including toggling the panel when a user selects its icon and updating the displayed panel when the current asset changes. + +The host is also responsible for rendering the panel header. + +The extension only declares the icon type, panel title, and URL for the custom panel content. + +## API Reference + +This API reference is divided into two parts: the API provided by AEM Assets Content Hub to the extension and the API provided by the extension to AEM Assets Content Hub. + +### Host API Reference + +In addition to the [Common APIs](../commons/index.md) provided by AEM Assets Content Hub to all extensions, the host application provides the following API specific to Asset Details. + +#### `assetDetails.getCurrentAsset()` + +**Description:** returns the ID of the asset currently displayed in Asset Details. + +**Returns** (`string`): Current asset ID. + +**Example:** + +```jsx +const assetId = await guestConnection.host.assetDetails.getCurrentAsset(); +``` + +### Extension API Reference + +The extension definition object passed to the `register()` function defines the `assetDetails` namespace. + +#### assetDetails namespace + +The `assetDetails` namespace includes the following method: + +- `getTabPanels()` + +#### `assetDetails.getTabPanels()` + +**Description:** returns an array of custom panel descriptors that the extension wants to add to Asset Details. + +**Returns** (`array`): An array of custom panel descriptors, or an empty array if no custom panels should be added. + +Each array element is a custom panel descriptor with the following properties: + +| Property | Type | Description | +| --- | --- | --- | +| `id` | `string` | Panel ID, unique within the extension. | +| `tooltip` | `string` | Icon tooltip. | +| `title` | `string` | Custom panel title. | +| `icon` | `string` | Name of the [React Spectrum workflow icon](https://react-spectrum.adobe.com/icons.html#available-icons). | +| `contentUrl` | `string` | Relative route to the panel content. | + +## Example of adding a custom panel + +These code snippets demonstrate how the [AEM Assets Content Hub sample extension](https://github.com/adobe/aem-uix-examples/tree/main/aem-assets-contenthub-sample) creates a custom panel using the UIX SDK and adds it to Asset Details. The examples focus on the relevant code and omit some imports and other non-essential details. + +The main application defines default routes for the `ExtensionRegistration` component and an `asset-details-extension-tab` route for the `PanelAssetDetailsExtensionTab` component. AEM Assets Content Hub loads this route when the user selects the custom panel icon: + +```jsx +function App() { + return ( + + + + } /> + } /> + } + /> + + + + ); +} + +export default App; +``` + +The `ExtensionRegistration` component initializes the extension by calling the `register()` function provided by `@adobe/uix-guest`. The object passed to `register()` declares the `assetDetails` namespace and its `getTabPanels()` method: + +```jsx +function ExtensionRegistration() { + const init = async () => { + await register({ + id: 'extension-id', + methods: { + assetDetails: { + getTabPanels() { + return [ + { + id: 'asset-details-extension-tab', + tooltip: 'Asset Details Extension Tab', + icon: 'Extension', + title: 'Asset Details Extension Tab', + contentUrl: '/#asset-details-extension-tab' + } + ]; + } + } + } + }); + }; + + init().catch(console.error); + + return IFrame for integration with Host (Content Hub)...; +} + +export default ExtensionRegistration; +``` + +The `PanelAssetDetailsExtensionTab` component renders the custom panel content. It uses the `attach()` function provided by `@adobe/uix-guest` to establish a connection with AEM Assets Content Hub. The component then uses this connection to display a toast message when the user selects the button: + +```jsx +export default function PanelAssetDetailsExtensionTab() { + const [guestConnection, setGuestConnection] = useState(); + + useEffect(() => { + (async () => { + const connection = await attach({id: 'extension-id'}); + setGuestConnection(connection); + })(); + }, []); + + function displayToast(variant, message) { + guestConnection.host.toast.display({variant, message}); + } + + return ( + + + + + + + + + + ); +} +``` + +Panel content can also use `assetDetails.getCurrentAsset()` to retrieve the current asset ID: + +```jsx +const assetId = await guestConnection.host.assetDetails.getCurrentAsset(); +``` + +See the complete [registration component](https://github.com/adobe/aem-uix-examples/blob/main/aem-assets-contenthub-sample/src/aem-assets-contenthub-1/web-src/src/components/ExtensionRegistration.js) and [custom panel component](https://github.com/adobe/aem-uix-examples/blob/main/aem-assets-contenthub-sample/src/aem-assets-contenthub-1/web-src/src/components/PanelAssetDetailsExtensionTab.js) in the sample application. \ No newline at end of file diff --git a/src/pages/services/aem-assets-content-hub/api/card-actions/asset-card-action.webp b/src/pages/services/aem-assets-content-hub/api/card-actions/asset-card-action.webp new file mode 100644 index 00000000..93e806ab Binary files /dev/null and b/src/pages/services/aem-assets-content-hub/api/card-actions/asset-card-action.webp differ diff --git a/src/pages/services/aem-assets-content-hub/api/card-actions/collection-card-action.webp b/src/pages/services/aem-assets-content-hub/api/card-actions/collection-card-action.webp new file mode 100644 index 00000000..7e23d755 Binary files /dev/null and b/src/pages/services/aem-assets-content-hub/api/card-actions/collection-card-action.webp differ diff --git a/src/pages/services/aem-assets-content-hub/api/card-actions/index.md b/src/pages/services/aem-assets-content-hub/api/card-actions/index.md new file mode 100644 index 00000000..fc41b7f6 --- /dev/null +++ b/src/pages/services/aem-assets-content-hub/api/card-actions/index.md @@ -0,0 +1,238 @@ +--- +title: Card Actions - AEM Assets Content Hub Extensibility +description: Add custom actions to Asset Cards and Collection Cards in AEM Assets Content Hub. +contributors: + - https://github.com/AdobeDocs/uix +--- + +# Card Actions + +AEM Assets Content Hub offers the ability to add custom actions to Asset Cards and Collection Cards. + +An Asset Card represents an asset in Content Hub. A Collection Card represents a collection. Each card provides an action menu associated with that resource. + +Extensions should use the unified `aem/assets/contenthub/1` extension point to customize Card Actions. + +## Custom Asset Card and Collection Card actions + +This extensibility feature allows context-aware customization of the action menu associated with an Asset Card or Collection Card. + +Using the `card` namespace, custom actions can be added after the built-in actions. A custom action can adapt its label, icon, and behavior to the current context and selected resource. + +In this example, a custom **Asset label** action is added to an Asset Card action menu: + +![Custom Asset Card action in AEM Assets Content Hub](asset-card-action.webp) + +In this example, a custom **Collection label** action is added to a Collection Card action menu: + +![Custom Collection Card action in AEM Assets Content Hub](collection-card-action.webp) + +## API Reference + +This API reference is divided into two parts: the API provided by AEM Assets Content Hub to the extension and the API provided by the extension to AEM Assets Content Hub. + +### Host API Reference + +Card Actions can use the [Common APIs](../commons/index.md) provided by AEM Assets Content Hub to all extensions. The host communicates the current context and selected resource through the `card` extension API callbacks described below. + +### Card context + +AEM Assets Content Hub supports Card Actions in two contexts. The current context is communicated to the extension APIs so custom code can adapt to the current area of Content Hub. + +- **Asset Cards:** The action context is `assets`. When an action is selected, the resource type is `asset`. +- **Collection Cards:** The action context is `collections`. When an action is selected, the resource type is `collection`. + +Asset Cards report the `assets` context in the main assets view, within collections, and in link shares. Only Collection Cards report the `collections` context. + +### Extension API Reference + +The extension definition object passed by the extension to the `register()` function defines the `card` namespace. + +The methods in this namespace provide the capabilities to: + +- Add custom actions to Asset Cards and Collection Cards. +- Handle user interaction with a custom Card Action. + +#### card namespace + +The `card` namespace includes these two methods: + +- `getActionButtons(actionContext)` +- `onActionClick(resourceType, buttonId, resourceId, actionContext)` + +#### `card.getActionButtons(actionContext)` + +**Description:** returns an array of custom action descriptors or an empty array if no custom actions should be added in the specified context. + +**Parameters:** + +- `actionContext` (`object`): Object representing the current Card Action context. + - `context` (`string`): Current context. Possible values are `assets` and `collections`. + +**Returns** (`array`): An array of custom action descriptors, or an empty array if no custom actions should be added. + +Each array element is a custom action descriptor with the following properties: + +- `id` (`string`): Action ID, unique within the extension. +- `label` (`string`): Custom action title. +- `icon` (`string`): Name of the [React Spectrum workflow icon](https://react-spectrum.adobe.com/icons.html#available-icons). + +**Example:** + +```jsx +card: { + getActionButtons({context}) { + return [ + { + id: 'customId', + label: context === 'collections' ? 'Collection action' : 'Asset action', + icon: 'Form' + } + ]; + } +} +``` + +#### `card.onActionClick(resourceType, buttonId, resourceId, actionContext)` + +**Description:** handles activation of a custom action for the selected Asset Card or Collection Card. + +**Parameters:** + +- `resourceType` (`string`): Selected resource type. Possible values are `asset` and `collection`. +- `buttonId` (`string`): ID of the activated custom action. +- `resourceId` (`string`): ID of the selected asset or collection. +- `actionContext` (`object`): Object representing the current Card Action context. + - `context` (`string`): Current context. Possible values are `assets` and `collections`. + +**Example:** + +```jsx +async onActionClick(resourceType, buttonId, resourceId, {context}) { + if (buttonId === 'customId') { + // Handle the action for the selected resource. + } +} +``` + +## Examples + +These code snippets demonstrate how the [AEM Assets Content Hub sample extension](https://github.com/adobe/aem-uix-examples/tree/main/aem-assets-contenthub-sample) adds a custom action to Asset Cards and Collection Cards and opens a custom dialog when the action is selected. The examples focus on the relevant code and omit some imports and other non-essential details. + +The `ExtensionRegistration` component initializes the extension registration process by calling the `register()` function provided by the `@adobe/uix-guest` library. + +The object passed to `register()` describes the extension and its capabilities. In particular, it declares that the extension uses the `card` namespace and its `getActionButtons()` and `onActionClick()` methods: + + +```jsx +function ExtensionRegistration() { + const init = async () => { + const guestConnection = await register({ + id: 'extension-id', + methods: { + card: { + getActionButtons() { + return [ + { + id: 'customId', + label: 'Custom label', + icon: 'Form' + } + ]; + }, + async onActionClick(resourceType, buttonId, resourceId) { + if (buttonId === 'customId') { + await guestConnection.host.modal.openDialog({ + title: 'Custom Dialog', + contentUrl: `/#card-action-modal?resourceId=${encodeURIComponent(resourceId)}&resourceType=${encodeURIComponent(resourceType)}`, + type: 'modal', + size: 'M' + }); + } + } + } + } + }); + }; + + init().catch(console.error); + + return IFrame for integration with Host (Content Hub)...; +} + +export default ExtensionRegistration; +``` + +### Example of context-aware Card Actions + +The `context` value can be used to return different actions for Asset Cards and Collection Cards. In this example, the extension adds one action only to Asset Cards and a different action only to Collection Cards: + +```jsx +card: { + getActionButtons({context}) { + if (context === 'assets') { + return [ + { + id: 'assetAction', + label: 'Asset action', + icon: 'Image' + } + ]; + } + + if (context === 'collections') { + return [ + { + id: 'collectionAction', + label: 'Collection action', + icon: 'Folder' + } + ]; + } + + return []; + } +} +``` + +### Example of handling a Card Action + +The sample passes the selected `resourceId` and `resourceType` to a custom dialog through the dialog URL. The dialog route reads those values, connects to AEM Assets Content Hub using `attach()`, and can close itself using the Modal API: + +```jsx +export default function CardActionModal() { + const [guestConnection, setGuestConnection] = useState(null); + const [resource, setResource] = useState(null); + + useEffect(() => { + (async () => { + const params = new URLSearchParams(window.location.hash.split('?')[1] || ''); + setResource({ + resourceId: params.get('resourceId'), + resourceType: params.get('resourceType') + }); + + const connection = await attach({id: 'extension-id'}); + setGuestConnection(connection); + })(); + }, []); + + return ( + + + Custom Dialog + Resource Type: {resource?.resourceType} + Resource ID: {resource?.resourceId} + + + + ); +} +``` + +See the complete [registration component](https://github.com/adobe/aem-uix-examples/blob/main/aem-assets-contenthub-sample/src/aem-assets-contenthub-1/web-src/src/components/ExtensionRegistration.js) and [Card Action dialog component](https://github.com/adobe/aem-uix-examples/blob/main/aem-assets-contenthub-sample/src/aem-assets-contenthub-1/web-src/src/components/CardActionModal.js) in the sample application. \ No newline at end of file diff --git a/src/pages/services/aem-assets-content-hub/api/commons/index.md b/src/pages/services/aem-assets-content-hub/api/commons/index.md new file mode 100644 index 00000000..90b820d3 --- /dev/null +++ b/src/pages/services/aem-assets-content-hub/api/commons/index.md @@ -0,0 +1,291 @@ +--- +title: Common Concepts in Creating Extensions +description: Understand the fundamentals required to develop an extension for AEM Assets Content Hub. +contributors: + - https://github.com/AdobeDocs/uix +--- + +# Common Concepts in Creating Extensions + +Understand the fundamentals required to develop an extension for AEM Assets Content Hub. + +## Extension Point + +AEM Assets Content Hub has a unified `aem/assets/contenthub/1` extension point that allows you to customize Asset Details, Asset Cards, Collection Cards, and the Selection Bar from a single extension. To use it, add the following configuration to `app.config.yaml` at the root of your extension: + +```yaml +extensions: + aem/assets/contenthub/1: + $include: src/aem-assets-contenthub-1/ext.config.yaml +``` + +Here is an example of the `ext.config.yaml` file: + +```yaml +operations: + view: + - type: web + impl: index.html +actions: actions +web: web-src +``` + +The [AEM Assets Content Hub sample application](https://github.com/adobe/aem-uix-examples/tree/main/aem-assets-contenthub-sample) contains a complete configuration and application structure. + +## Extension Registration + +Interaction between a UI Extension and AEM Assets Content Hub starts with the initialization process that includes the extension's capabilities registration so Content Hub knows when to invoke the extension and which APIs to expose. Registration is done by calling the `register()` function provided by the `@adobe/uix-guest` library. This asynchronous function takes a single object that describes the extension and returns an object representing the connection to Content Hub. + +The `register()` function should be invoked after the extension initialization page is loaded. + +Extension registration data must include: + +- `id`: A string with a unique extension identifier. This identifier is useful for debugging the interaction between Content Hub and the extension and is required when the extension provides custom UI. +- `methods`: Objects containing the extension APIs exposed to Content Hub. All methods are grouped into **namespaces** that represent more granular areas of Content Hub functionality within the extension point. + +The following namespaces are available under `aem/assets/contenthub/1`: + +- `assetDetails`, which allows adding [custom panels](../asset-details/index.md) to Asset Details. +- `card`, which allows adding [Card Actions](../card-actions/index.md) to Asset Cards and Collection Cards. Content Hub identifies the area through the `assets` or `collections` context. +- `selectionBar`, which allows adding [Selection Bar actions](../selection-bar/index.md) for workflows that operate on selected assets. + +Implement only the namespaces your extension needs. A single extension can combine all namespaces in one `register()` call: + +```jsx +import {register} from '@adobe/uix-guest'; + +const guestConnection = await register({ + id: 'extension-id', + methods: { + assetDetails: { + getTabPanels() { + return []; + } + }, + card: { + getActionButtons(actionContext) { + return []; + }, + onActionClick(resourceType, buttonId, resourceId, actionContext) { + // Handle an Asset Card or Collection Card action. + } + }, + selectionBar: { + getActionButtons(actionContext) { + return []; + }, + onActionClick(buttonId, assetIds) { + // Handle an action for the selected assets. + } + } + } +}); +``` + +See [Asset Details](../asset-details/index.md), [Card Actions](../card-actions/index.md), and [Selection Bar](../selection-bar/index.md) for each namespace's methods and descriptors. + +## Building Extension UI + +Namespaces that render extension content require the extension to provide its own interface. For example, an Asset Details panel or a modal opened from a Card Action should be implemented as a separate route in the extension web application. Content Hub loads that route in an iframe. + +The iframe page normally needs data from Content Hub or needs to trigger an action in the host application. Call `attach()` from `@adobe/uix-guest` inside the iframe route to establish communication with Content Hub: + +```jsx +import {attach} from '@adobe/uix-guest'; + +const guestConnection = await attach({id: 'extension-id'}); +const aemHost = await guestConnection.host.discovery.getAemHost(); +``` + +The ID passed to `attach()` must match the ID used during extension registration. + +## Set Up Communication with Content Hub + +Both `register()` and `attach()` return a connection object. Its `host` property exposes Content Hub APIs to UI Extensions. Through these APIs, an extension can access host information and invoke actions in Content Hub. + +## Common APIs exposed by AEM Assets Content Hub to all UI Extensions + +The APIs documented below are available to all AEM Assets Content Hub UI Extensions, irrespective of the extension point they are using. + +Every API is defined under its own namespace, which in turn is contained within the `host` object of the connection instance. + +All API invocations are asynchronous and return a `Promise`. + +### Authentication API + +This API provides information about the current Org, access token, and API key in AEM Assets Content Hub. The API uses the `auth` namespace. + +#### `auth.getIMSInfo()` + +**Description:** returns information about the IMS Org name, ID, and access token. + +**Return Object Structure** + +- `imsOrg` (`string`): The IMS organization identifier. +- `imsOrgName` (`string`): The name of the IMS organization. +- `accessToken` (`string`): The access token for IMS. + +#### `auth.getApiKey()` + +**Description:** returns the API key used by AEM Assets Content Hub. + +**Returns** (`string`): API key + +**Example:** + +```js +const {imsOrg, accessToken} = await guestConnection.host.auth.getIMSInfo(); + +const apiKey = await guestConnection.host.auth.getApiKey(); +``` + +### Discovery API + +This API provides information about the AEM Assets Content Hub delivery repository location. + +#### `discovery.getAemHost()` + +**Description:** returns the URL of the AEM delivery repository. + +**Returns** (`string`): AEM delivery repository URL + +**Example:** + +```js +const aemHost = await guestConnection.host.discovery.getAemHost(); +``` + +### Toast API + +This API provides methods to show toast messages in AEM Assets Content Hub. + +#### `toast.display({variant, message})` + +**Description:** shows a toast message in AEM Assets Content Hub. + +**Parameters:** + +- **options** (`object`): Object with the following properties: + - `variant` (`string`, optional): The type of toast message. Possible values are `neutral`, `positive`, `info`, and `negative`. The default value is `info`. + - `message` (`string`, required): The message to display in the toast. + +**Example:** + +```js +guestConnection.host.toast.display({variant: 'positive', message: 'Asset saved successfully'}); +``` + +### i18n API + +This API provides methods to support localization of the UI Extension. + +#### `i18n.getLocalizationInfo()` + +**Description:** returns information about the current locale used in AEM Assets Content Hub. + +**Return Object Structure** + +- `locale` (`string`): The current locale used in AEM Assets Content Hub. + +**Example:** + +```js +const {locale} = await guestConnection.host.i18n.getLocalizationInfo(); +``` + +### Modal API + +This API provides methods to open a modal dialog in the host application, close it, and retrieve its associated payload. + +#### `modal.openDialog(options)` + +**Description:** opens a dialog using the provided configuration. The dialog content is loaded from a specified URL. + +**Parameters:** + +- **options** (`object`): Object with the following dialog configuration properties: + - `title` (`string`, optional): The title of the dialog. + - `contentUrl` (`string`): Relative route to the dialog content. + - `type` (`string`, optional): The dialog type. Possible values are `modal` and `fullscreen`. The default value is `modal`. + - `size` (`string`, optional): The dialog size. Possible values are `S`, `M`, and `L`. The default value is `M`. This value is ignored when the dialog type is `fullscreen`. + - `payload` (`any`, optional): Arbitrary data the extension passes to the dialog. The dialog can retrieve this data using `modal.getPayload()`. + +**Example:** + +The extension application defines a route that renders the custom dialog content. The component for that route calls `attach()` from `@adobe/uix-guest` to establish a connection with AEM Assets Content Hub: + +```jsx +import React, {useEffect, useState} from 'react'; +import {attach} from '@adobe/uix-guest'; + +export default function ModalCustomAction() { + const [guestConnection, setGuestConnection] = useState(); + + useEffect(() => { + (async () => { + const connection = await attach({id: 'extension-id'}); + setGuestConnection(connection); + })(); + }, []); + + function closeDialog() { + guestConnection.host.modal.closeDialog(); + } + + return ; +} +``` + +The custom dialog can be opened in AEM Assets Content Hub using `modal.openDialog()` with the dialog content URL, title, type, size, and an optional payload object. The dialog component can retrieve the payload using `modal.getPayload()`: + +```js +guestConnection.host.modal.openDialog({ + title: 'Custom Dialog', + contentUrl: '/#modal-custom-action', + type: 'modal', + size: 'S', + payload: {assetId: 'urn:aaid:aem:example'} +}); +``` + +#### `modal.closeDialog()` + +**Description:** closes the currently active dialog. + +**Example:** + +```js +guestConnection.host.modal.closeDialog(); +``` + +#### `modal.getPayload()` + +**Description:** returns the payload object passed by the extension when calling `modal.openDialog()`. + +**Returns** an optional arbitrary payload object. + +**Example:** + +```js +const payload = await guestConnection.host.modal.getPayload(); +// Work with the payload. +``` + +## Asset Details API + +In addition to the common APIs, the `assetDetails` namespace exposes `assetDetails.getCurrentAsset()` to extension content loaded in Asset Details. See [Asset Details](../asset-details/index.md) for details. + +## Repository Targeting + +An extension can limit registration to approved Content Hub repositories. Read the `repo` query parameter from the initialization URL and compare it with the repositories configured for the extension: + +```js +const params = new URLSearchParams(window.location.search); +const repo = params.get('repo'); + +if (allowedRepos.includes(repo)) { + await registerExtension(); +} +``` + +See the [sample registration component](https://github.com/adobe/aem-uix-examples/blob/main/aem-assets-contenthub-sample/src/aem-assets-contenthub-1/web-src/src/components/ExtensionRegistration.js) for a complete implementation. \ No newline at end of file diff --git a/src/pages/services/aem-assets-content-hub/api/index.md b/src/pages/services/aem-assets-content-hub/api/index.md new file mode 100644 index 00000000..fbf6a2af --- /dev/null +++ b/src/pages/services/aem-assets-content-hub/api/index.md @@ -0,0 +1,48 @@ +--- +title: The AEM Assets Content Hub Extension Point +description: Learn how to use the extension point available in AEM Assets Content Hub. +contributors: + - https://github.com/AdobeDocs/uix +--- + +# The AEM Assets Content Hub Extension Point + +This section covers the utilization of the extension point, extension registration, and common methods that can be used in any application that leverages the extension point for Content Hub customization. + +## A single extension point for Content Hub + +AEM Assets Content Hub provides a unified extension point, `aem/assets/contenthub/1`, that combines Asset Details, Asset Card, Collection Card, and Selection Bar customization. A single extension registered under `aem/assets/contenthub/1` can customize all four areas from one App Builder extension, one deployment, and one `register()` call. + +The extensibility APIs are organized into namespaces, each covering an area of Content Hub functionality: + +| Namespace | Area | Purpose | +| --- | --- | --- | +| [`assetDetails`](asset-details/index.md) | Asset Details | Add a custom panel to Asset Details. | +| [`card`](card-actions/index.md) | Asset Cards and Collection Cards | Add actions using the `assets` context for Asset Cards and the `collections` context for Collection Cards. | +| [`selectionBar`](selection-bar/index.md) | Selection Bar | Add actions for workflows that operate on selected assets. | + +Implement only the namespaces your extension needs. The pages below describe each namespace and its methods in detail. + + + +[Common Concepts in Creating Extensions](commons/index.md) + +Learn about extension registration, host communication, and methods that can be used in any extension. + + + +[Asset Details](asset-details/index.md) + +Explore how to add a custom panel to Asset Details. + + + +[Card Actions](card-actions/index.md) + +Explore how to add actions to Asset Cards and Collection Cards. + + + +[Selection Bar](selection-bar/index.md) + +Explore how to add actions for workflows that operate on selected assets. \ No newline at end of file diff --git a/src/pages/services/aem-assets-content-hub/api/selection-bar/index.md b/src/pages/services/aem-assets-content-hub/api/selection-bar/index.md new file mode 100644 index 00000000..caee4221 --- /dev/null +++ b/src/pages/services/aem-assets-content-hub/api/selection-bar/index.md @@ -0,0 +1,70 @@ +--- +title: Selection Bar - AEM Assets Content Hub Extensibility +description: Add custom actions for selected resources in AEM Assets Content Hub. +contributors: + - https://github.com/AdobeDocs/uix +--- + +# Selection Bar + +**Selection Bar** is the bar with actions that appears when one or more assets or collections in AEM Assets Content Hub are selected. + +The Selection Bar API adds commands that operate on multiple selected resources. Content Hub displays these commands when the user selects assets or collections in a supported browsing surface. + +In this example, a custom action is added to the Selection Bar after the built-in actions: + +![Custom Selection Bar action in AEM Assets Content Hub](selection-bar-action.webp) + +## Register Selection Bar actions + +Implement `selectionBar.getActionButtons(actionContext)` to return action buttons. The action context contains the current surface and selected resources: + +```js +{ + context: 'assets', + resourceSelection: { + resources: [{id: 'urn:aaid:aem:...'}] + } +} +``` + +Implement `selectionBar.onActionClick(buttonId, resourceIds)` to handle a selected command. The array contains asset IDs when assets are selected and collection IDs when collections are selected. + +```jsx +const guestConnection = await register({ + id: 'extension-id', + methods: { + selectionBar: { + getActionButtons({resourceSelection}) { + if (resourceSelection.resources.length === 0) { + return []; + } + + return [ + { + id: 'copy-urls', + label: 'Copy URLs', + icon: 'Link' + } + ]; + }, + async onActionClick(buttonId, resourceIds) { + if (buttonId !== 'copy-urls') { + return; + } + + await guestConnection.host.modal.openDialog({ + title: 'Selected resources', + contentUrl: `/#selected-resources?resourceIds=${encodeURIComponent(JSON.stringify(resourceIds))}`, + type: 'modal', + size: 'M' + }); + } + } + } +}); +``` + +Selection Bar buttons use the same `id`, `label`, and `icon` properties as card action buttons. Content Hub passes `onActionClick()` an array containing the IDs of the selected resources. Use `actionContext.context` in `getActionButtons()` to determine the current browsing surface and return actions appropriate for that resource type. + +See the [sample registration component](https://github.com/adobe/aem-uix-examples/blob/main/aem-assets-contenthub-sample/src/aem-assets-contenthub-1/web-src/src/components/ExtensionRegistration.js) and [sample Selection Bar dialog](https://github.com/adobe/aem-uix-examples/blob/main/aem-assets-contenthub-sample/src/aem-assets-contenthub-1/web-src/src/components/SelectionBarModal.js) for a complete implementation. \ No newline at end of file diff --git a/src/pages/services/aem-assets-content-hub/api/selection-bar/selection-bar-action.webp b/src/pages/services/aem-assets-content-hub/api/selection-bar/selection-bar-action.webp new file mode 100644 index 00000000..50eb9e55 Binary files /dev/null and b/src/pages/services/aem-assets-content-hub/api/selection-bar/selection-bar-action.webp differ diff --git a/src/pages/services/aem-assets-content-hub/code-generation/index.md b/src/pages/services/aem-assets-content-hub/code-generation/index.md new file mode 100644 index 00000000..8dc5c7bd --- /dev/null +++ b/src/pages/services/aem-assets-content-hub/code-generation/index.md @@ -0,0 +1,168 @@ +--- +title: Code Generation +description: Create an AEM Assets Content Hub extension project from the maintained sample application. +contributors: + - https://github.com/AdobeDocs/uix +--- + +# Code Generation + +The [AEM Assets Content Hub sample application](https://github.com/adobe/aem-uix-examples/tree/main/aem-assets-contenthub-sample) provides the project structure and starter code for the `aem/assets/contenthub/1` extension point. Using the sample is optional, but we highly recommend it to save time and start with the correct UI Extension structure. + +## Launch code generation during project initialization + +You need to have AIO CLI version >= 9.1.0 to use the available templates. Please refer to [Local Environment Set Up](https://developer.adobe.com/uix/docs/guides/local-environment/). + +After creating a project on Adobe Developer Console and installing `@adobe/aio-cli`, start code generation using the sample application. + +Create a directory and run the following commands from that directory: + +1. Login to Adobe I/O. + +```shell +➜ demo-extension-project % aio login +``` + +Follow the link to authenticate your account. + +2. Verify Your Current Context. + +```shell +➜ demo-extension-project % aio where +``` + +You should see: + +```text +1. Org: +2. Project: +3. Workspace: +``` + +3. Select the Appropriate org, project and workspace. + +```shell +➜ demo-extension-project % aio console org select +➜ demo-extension-project % aio console project select +➜ demo-extension-project % aio console workspace select +``` + +4. [Fetch your GitHub PAT (Personal Access Token)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) and perform app init. Select the appropriate organization. + +```shell +➜ demo-extension-project % aio app init --repo adobe/aem-uix-examples/aem-assets-contenthub-sample --github-pat +``` + +5. The same initialization command prompts you to select your organization and then your project within that organization. + +You can either select the project by scrolling or filter the list of projects by beginning to type the project name. + +```shell +:heavy_check_mark: Downloaded quickstart repo + +? Select Org: + +❯ Alpha Org + Beta Org + Delta Org + +? Select a Project, or press + to create new: + great-project +❯ useful-project + awesome-project + +Project initialized for Workspace Stage, you can run 'aio app use -w ' to switch workspace. + +:heavy_check_mark: App initialization finished! +``` + +> Tip: you can add more actions, web-assets and events to your project via the `aio app add` commands. + +After this step, we will have a generated project structure with necessary npm dependencies are getting installed. + +If you have worked with an Adobe App Builder App before, you will notice that you have generated a starter project of a UI Extension that implements [extension points](https://developer.adobe.com/app-builder/docs/guides/extensions/). + +```text +. +|-- README.md +|-- app.config.yaml +|-- extension-manifest.json +|-- hooks +| `-- post-deploy.js +|-- jest.setup.js +|-- package.json +`-- src + `-- aem-assets-contenthub-1 + |-- actions + |-- e2e + |-- ext.config.yaml + |-- test + `-- web-src + |-- index.html + `-- src + |-- components + | |-- App.js + | |-- CardActionModal.js + | |-- Constants.js + | |-- ExtensionRegistration.js + | |-- PanelAssetDetailsExtensionTab.js + | `-- SelectionBarModal.js + |-- index.css + |-- index.js + `-- utils.js +``` + +The root `app.config.yaml` declares the unified Content Hub extension point: + +```yaml +extensions: + aem/assets/contenthub/1: + $include: src/aem-assets-contenthub-1/ext.config.yaml +``` + +Keep the `aem/assets/contenthub/1` key in `app.config.yaml`. The key identifies the Content Hub extension point and is not an application-specific name. + +The `allowedRepos` array in `ExtensionRegistration.js` contains the list of repository names that the extension is allowed to register with. To ensure that your extension works correctly, update the array with the repository IDs you want to configure. + +Format: `delivery-pxxx-eyyy.adobeaemcloud.com` + +Example: + +```js +const allowedRepos = ['delivery-p12345-e167890.adobeaemcloud.com']; +``` + +## Configure the extension + +Update the sample before running it: + +1. Set a stable, unique `extensionId` in `Constants.js`. +2. Keep only the registration namespaces and application routes required by the extension. +3. Replace sample labels, icons, panel descriptors, and action handlers with the application behavior. +4. Update package and manifest metadata for the project. + +The sample demonstrates all four Content Hub surfaces: + +- `assetDetails` for a custom Asset Details panel +- `card` with the `assets` context for Asset Card actions +- `card` with the `collections` context for Collection Card actions +- `selectionBar` for actions on selected assets or collections + +See [Extension Points](../api/index.md) for the API contracts. + +## Build and validate the project + +Build the web application and Runtime actions: + +```bash +aio app build +``` + +Run the automated tests: + +```bash +aio app test +aio app test --e2e +``` + +Continue with [Step-by-Step Extension Development](../extension-development/index.md) to run and preview the extension in Content Hub. \ No newline at end of file diff --git a/src/pages/services/aem-assets-content-hub/debug/index.md b/src/pages/services/aem-assets-content-hub/debug/index.md new file mode 100644 index 00000000..d1e7eaaf --- /dev/null +++ b/src/pages/services/aem-assets-content-hub/debug/index.md @@ -0,0 +1,181 @@ +--- +title: Troubleshooting - AEM Assets Content Hub Extensibility +description: Resolve common local development and preview issues for AEM Assets Content Hub extensions. +contributors: + - https://github.com/AdobeDocs/uix +--- + +# Troubleshooting - AEM Assets Content Hub Extensibility + +The ability to get fast feedback and see if the code works as expected is crucial for rapid development. A developer may connect a locally running UI Extension to AEM Assets Content Hub, link it to the correct delivery repository, and verify changes before deployment and extension publication. + +## Running in local environment + +There are two options to run an extension locally: + +1. Complete local environment isolation. In this case, both the front-end code of your extension and the serverless actions run locally. This mode is enabled with the `aio app dev` command. +2. Partial isolation using the `aio app run` command, where the extension still uses Adobe I/O Runtime and deploys server-side functions in Adobe cloud. + +For both options, the local development server with file change monitoring will be started to serve the UI Extension front-end. + +Regardless of where the server-side handlers are running, in local containers or on Adobe I/O Runtime, the developer can connect a debugger to trace script execution. + +### Complete local environment isolation + +```shell +➜ demo-extension-project % aio app dev +``` + +This will deploy the actions to a local [OpenWhisk](https://openwhisk.apache.org/) instance, which the [Adobe I/O CLI](https://github.com/adobe/aio-cli) automatically downloads and installs. The extension SPA runs on the local machine. + +```shell +➜ demo-extension-project % aio app dev +To view your local application: + -> https://localhost:9080 +To view your deployed application in the Experience Cloud shell: + -> https://experience.adobe.com/?devMode=true#/custom-apps/?localDevUrl=https://localhost:9080 +press CTRL+C to terminate the dev environment +``` + +### Use Adobe I/O Runtime to deploy server-side handlers + +```shell +➜ demo-extension-project % aio app run +``` + +This will deploy the actions to [Adobe I/O Runtime](https://developer.adobe.com/runtime/) while running the UI part on the local machine. + +```shell +➜ demo-extension-project % aio app run + create .vscode/launch.json + +No change to package.json was detected. No package manager install will be executed. + +To view your local application: + -> https://localhost:9080 +To view your deployed application in the Experience Cloud shell: + -> https://experience.adobe.com/?devMode=true#/custom-apps/?localDevUrl=https://localhost:9080 +press CTRL+C to terminate dev environment +``` + +Now your UI Extension is reachable using the URL shown in the Terminal. + +### UI Extension endpoint + +Once the local runtime starts, the extension endpoint is returned as the `To view your local application` URL. You need this URL to embed the locally running extension in AEM Assets Content Hub. + +### Accept the Certificate + +If you are using this application for the first time, you will see a message similar to: + +```shell +success: generated certificate +A self signed development certificate has been generated, you will need to accept it in your browser in order to use it. +Waiting for the certificate to be accepted.... timed out +``` + +This message appears because the local development server uses an SSL certificate for secure communication. Learn more about the purpose of this certificate in [Certificates for localhost](https://letsencrypt.org/docs/certificates-for-localhost/). + +Navigate to `https://localhost:9080`. In Google Chrome, you should see a screen similar to this: + +![Certificate warning](https://developer.adobe.com/uix/docs/services/aem-assets-view/debug/media_1fd0c90f4af88b47b10ed82e4d04aa57878094740.png?width=750&format=png&optimize=medium) + +Select **Advanced**. The next screen may vary by browser, but you should see an option to select **Proceed to localhost (unsafe)** to accept the certificate. + +![Accept the certificate](https://developer.adobe.com/uix/docs/services/aem-assets-view/debug/media_1bbaeee2d74f68015e879c951b4f1e5e24e6a12c6.png?width=750&format=png&optimize=medium) + +Alternatively, in Google Chrome you may type `thisisunsafe`. Refer to your browser's documentation for instructions on accepting a self-signed certificate. + +You may need to exit the current process and run `aio app run` again. If the command selected another port, open that port instead. + +## Load UI Extension + +Using the extension endpoint URL returned by the run command, you may embed the locally running extension in AEM Assets Content Hub: + +1. Navigate to AEM Assets Content Hub. +2. Add the following query parameters to the URL: + - `devMode=true` instructs Adobe Experience Shell to allow content from localhost. + - `ext=` specifies the full extension endpoint URL. You may use multiple `ext` parameters to test several extensions at the same time. + - `repo=` specifies the Content Hub delivery repository. +3. Reload AEM Assets Content Hub with the added extension. + +The AEM Assets Content Hub URL should look similar to `https://experience.adobe.com/?devMode=true&ext=https://localhost:9080&repo=delivery-p12345-e123456.adobeaemcloud.com#/assets/contenthub/`. + +### `ext=` query parameter + +The `ext` query parameter supports different syntax variations depending on the number of extensions to load and their extension points. + +The complete syntax of the `ext=` query parameter is: + +```text +ext.=[,] +``` + +Where: + +- `ExtensionPointId` is the ID of the extension point in AEM Assets Content Hub. +- `url` is the URL of the extension to load. + +You may specify multiple `ext` parameters with different extension point IDs to load extensions for different extension points. You may also specify multiple extension URLs for the same extension point by separating them with a comma. + +**Example:** + +`ext.aem%2fassets%2fcontenthub%2f1=https://localhost:9080` loads the locally running extension from `https://localhost:9080` and applies it to the `aem/assets/contenthub/1` extension point. + +The `ext` parameter can also be used without specifying the extension point ID: + +```text +ext=[,] +``` + +In this case, AEM Assets Content Hub applies the extension to all available extension points. + +## Additional troubleshooting + +### Registration is skipped + +The sample can restrict registration with the `allowedRepos` array. Confirm that it contains the delivery repository passed in the initialization URL's `repo` query parameter. + +Use browser developer tools to inspect the extension iframe and look for the registration log or an error from `register()`. + +### The extension is deployed but not visible to some users + +If the App Builder project includes Adobe services that are not required by the extension, only users with access to those services may be able to see it. + +Remove all non-required services from the App Builder project's **Products and Services** section in Adobe Developer Console. Keep Adobe I/O Runtime, then redeploy the extension and create a new approval request. + +### The extension appears only with the `ext` URL parameter + +The extension may have been deployed or approved in a different workspace than the one currently selected. The `ext` parameter bypasses the normal registration flow used by an approved extension. + +Select the Production workspace, redeploy the extension, and create a new approval request: + +```bash +aio app use -w Production +aio app deploy +``` + +### OAuth token is invalid + +The following error indicates that the Adobe I/O CLI OAuth token has expired or is invalid: + +```text +Error: [CoreConsoleAPISDK:ERROR_GET_PROJECT_BY_ID] 401 - Unauthorized +``` + +Log out, log in again, and select the intended Adobe Developer Console context: + +```bash +aio logout +aio login +aio console org select +aio console project select +aio console workspace select +aio app use -g +``` + +Do not commit the generated `.env` file. + +## More help + +For general local preview issues, see [Local Preview of UI Extensions](../../../guides/preview-extension-locally/index.md). For a working implementation, compare your project with the [AEM Assets Content Hub sample application](https://github.com/adobe/aem-uix-examples/tree/main/aem-assets-contenthub-sample). \ No newline at end of file diff --git a/src/pages/services/aem-assets-content-hub/extension-development/index.md b/src/pages/services/aem-assets-content-hub/extension-development/index.md new file mode 100644 index 00000000..25c2fd0f --- /dev/null +++ b/src/pages/services/aem-assets-content-hub/extension-development/index.md @@ -0,0 +1,409 @@ +--- +title: Step-by-step Extension Development +description: Discover how to implement your first AEM Assets Content Hub extension. +contributors: + - https://github.com/AdobeDocs/uix +--- + +# Step-by-step AEM Assets Content Hub Extension Development + +The document helps you understand how to set up a local environment and start developing your first UI Extension for AEM Assets Content Hub. + +## About application + +This example application uses the unified `aem/assets/contenthub/1` extension point and demonstrates the three namespaces available in Content Hub: + +- `assetDetails` adds a custom panel to the Asset Details dialog. +- `card` adds actions to Asset Cards and Collection Cards. +- `selectionBar` adds actions for selected assets or collections. + +It includes the routes and UI for the Asset Details panel. The sample Card and Selection Bar actions open dialogs to demonstrate one possible implementation, but extensions are not required to open a dialog. This guide focuses on a single Asset Details panel to keep the example concise. + +Because it uses the unified extension point, the same extension can customize one or more of these surfaces by declaring the corresponding namespaces in the same `register()` call. You can keep only the namespaces and routes required by your extension. + +More information about AEM Assets Content Hub extension points can be found at [AEM Assets Content Hub Extension Points](../api/index.md). + +## Create a project in Adobe Developer Console + +UI Extensions, as with any App Builder application, are represented as projects in [Adobe Developer Console](https://developer.adobe.com/developer-console/docs/guides/). + + + +If you don't have access to the Adobe Developer Console, refer to the [How to Get Access](https://developer.adobe.com/uix/docs/guides/get-access/) guide for instructions. + +To begin, we need to create a new Project which will supply us with the configuration and resources. + +1. Sign in to [Adobe Developer Console](https://developer.adobe.com/console) with your Adobe ID. + + ![Sign in to Adobe Developer Console](https://developer.adobe.com/uix/docs/services/aem-assets-view/extension-development/media_1d7eb2297452d49b84136afb7d8a070a6d6ed54c3.png?width=750&format=png&optimize=medium) + +2. Choose your account. + + ![Choose your account](https://developer.adobe.com/uix/docs/services/aem-assets-view/extension-development/media_1e40d86d65a94310ce6b91dda03e4d556bad1f9aa.png?width=750&format=png&optimize=medium) + +3. Choose your profile or organization. + + ![Choose your profile](https://developer.adobe.com/uix/docs/services/aem-assets-view/extension-development/media_1aefe4eddf50149740a7cf7e68b697f368ee1df4e.png?width=750&format=png&optimize=medium) + +4. Make sure you are in a proper organization (a switcher is in the right top corner). + + ![Check organization](https://developer.adobe.com/uix/docs/services/aem-assets-view/extension-development/media_1d76d4e7ade35b61f23a87afba673261a66787906.png?width=750&format=png&optimize=medium) + +5. Click "Create new project" -> "Project from template": + + ![Create project from template](https://developer.adobe.com/uix/docs/services/aem-assets-view/extension-development/media_1b86c6056f4716428553c28e8636f8d564532134a.png?width=750&format=png&optimize=medium) + + And choose "App Builder": + + ![Choose "App Builder"](https://developer.adobe.com/uix/docs/services/aem-assets-view/extension-development/media_117ec87f78fce7538dbb8f85381017d70c59f4fb9.png?width=750&format=png&optimize=medium) + +6. Fill in the project data. + + ![Fill the project data](https://developer.adobe.com/uix/docs/services/aem-assets-view/extension-development/media_1fed75103fc1c7b180b8eb4861e276b05e095b616.png?width=750&format=png&optimize=medium) + +- `Project Title` is used to identify your project within [Adobe Developer Console](https://developer.adobe.com/console) and in [CLI](https://github.com/adobe/aio-cli). +- `App Name` will be used as a unique identifier for your application and this value cannot be changed after project creating. + +After creating, you should see a new project generated with 2 default Workspaces. Each App Builder project has two default workspaces: `Production` and `Stage`. You can add more workspaces as needed. The `Production` workspace is special, as it is used for the submission and distribution flow. + +![A new project with 2 default Workspaces](https://developer.adobe.com/uix/docs/services/aem-assets-view/extension-development/media_18da401dc2bba6e24721d6d63eb4eeb3934970ad5.png?width=750&format=png&optimize=medium) + +## Setting up local environment + +- [Node.js](https://nodejs.org/) + [npm (package manager)](https://docs.npmjs.com/). Make sure you are using the latest stable version of `Node.js` and `npm`. + +```shell +$ node -v + v20.9.0 +``` + +```shell +$ npm -v +10.1.0 +``` + +These are the current versions at the moment of creating the documentation. Make sure you are using the latest versions supported by Adobe I/O when you create the application. + +If you already have [Adobe I/O CLI](https://github.com/adobe/aio-cli) on your local, please ensure you use the latest version of the library. You can check the version through: + +```shell +aio -v +``` + +and compare it with + +```shell +npm show @adobe/aio-cli +``` + +If your version is outdated, update your `Adobe I/O CLI` by running + +```shell +npm install -g @adobe/aio-cli +``` + +More details are described in [Local environment set up](https://developer.adobe.com/uix/docs/guides/local-environment/). + +## Initialize your extension using the AIO CLI and generate a base structure from the sample application + +First, we need to sign in from CLI and bootstrap our project. Please complete all the steps described in [Code Generation for the AEM Assets Content Hub Extension](../code-generation/index.md). + +Also, we will not add an Adobe I/O action to our extension. + +After generating the project, return to this guide for an overview of the generated components and instructions for testing the extension in Content Hub. + +If you have worked with an Adobe App Builder App before, you will notice that you have generated a starter project of a UI Extension that implements [extension points](https://developer.adobe.com/app-builder/docs/guides/extensions/). + +```text +. +|-- README.md +|-- app.config.yaml +|-- extension-manifest.json +|-- hooks +| `-- post-deploy.js +|-- jest.setup.js +|-- package-lock.json +|-- package.json +`-- src + `-- aem-assets-contenthub-1 + |-- actions + |-- e2e + |-- ext.config.yaml + |-- test + `-- web-src + |-- index.html + `-- src + |-- components + | |-- App.js + | |-- CardActionModal.js + | |-- Constants.js + | |-- ExtensionRegistration.js + | |-- PanelAssetDetailsExtensionTab.js + | `-- SelectionBarModal.js + |-- index.css + |-- index.js + `-- utils.js +``` + +```yaml +# app.config.yaml +extensions: + aem/assets/contenthub/1: + $include: src/aem-assets-contenthub-1/ext.config.yaml +``` + +## Overview of generated components + +### Routing + +The root component `src/aem-assets-contenthub-1/web-src/src/components/App.js` contains the routing for the application. It defines the following routes: + +- the first two are the default routes which trigger the `ExtensionRegistration` component responsible for initial extension registration within the AEM Assets Content Hub application. +- the `asset-details-extension-tab` route which invokes the `PanelAssetDetailsExtensionTab` component responsible for rendering the custom panel content. This route gets called by the AEM Assets Content Hub application when the user clicks the custom panel icon. During the registration the extension will specify `/#asset-details-extension-tab` as content location. +- the `card-action-modal` route which invokes the `CardActionModal` component used by the sample Card action. This route gets called when the sample action opens its dialog. During the registration the extension will specify `/#card-action-modal` as content location. +- the `selection-bar-modal` route which invokes the `SelectionBarModal` component used by the sample Selection Bar action. This route gets called when the sample action opens its dialog. During the registration the extension will specify `/#selection-bar-modal` as content location. + +[React Router](https://reactrouter.com/start/declarative/routing) determines which part of the extension should be executed depending on the request. + +```js +import React from 'react'; +import ErrorBoundary from 'react-error-boundary'; +import { HashRouter as Router, Routes, Route } from 'react-router-dom'; +import ExtensionRegistration from './ExtensionRegistration'; +import PanelAssetDetailsExtensionTab from './PanelAssetDetailsExtensionTab'; +import CardActionModal from './CardActionModal'; +import SelectionBarModal from './SelectionBarModal'; + +function App() { + return ( + + + + } /> + } /> + } /> + } /> + } /> + + + + ); + + function onError(e, componentStack) {} + + function fallbackComponent({ componentStack, error }) { + return ( + +

+ Extension rendering error +

+
{componentStack + '\n' + error.message}
+
+ ); + } +} + +export default App; +``` + +Please note that your code may slightly differ from the given example depending on the version of the template for generation, but the main logic will be the same. + +Keep only the routes required by your extension. + +### Extension registration + +This logic component `src/aem-assets-contenthub-1/web-src/src/components/ExtensionRegistration.js` registers our extension with Content Hub as soon as it loads, so they can share data and communicate with each other. + +```js +import React from 'react'; +import { Text } from '@adobe/react-spectrum'; +import { register } from '@adobe/uix-guest'; +import { extensionId } from './Constants'; + +const allowedRepos = ['delivery-p12345-e167890.adobeaemcloud.com']; + +function getRepo() { + const search = new URLSearchParams(window.location.search); + return search.get('repo'); +} + +function shouldSkipRegistration(repo) { + return !allowedRepos.includes(repo); +} + +function ExtensionRegistration() { + const repo = getRepo(); + + if (shouldSkipRegistration(repo)) { + return Skipped registration because the repository is not allowed.; + } + + const init = async () => { + await register({ + id: extensionId, + methods: { + assetDetails: { + getTabPanels() { + return [ + { + id: 'asset-details-extension-tab', + tooltip: 'Asset Details Extension Tab', + icon: 'Extension', + title: 'Asset Details Extension Tab', + contentUrl: '/#asset-details-extension-tab' + } + ]; + } + } + } + }); + }; + + init().catch(console.error); + return IFrame for integration with Host (Content Hub)...; +} + +export default ExtensionRegistration; +``` + +We use the [UIX SDK Guest library](https://github.com/adobe/uix-sdk) and call the `register()` function, which connects to the host application and declares methods the host can call on the extension. + +The extension descriptor passed to the `register()` function in particular declares the [`getTabPanels()`](../api/asset-details/index.md#extension-api-reference) method, which in turn returns an array of custom panel descriptors upon a request from Content Hub. + +In case of our extension, `getTabPanels()` returns a panel descriptor that defines the panel ID, tooltip, icon, title, and content location. + +### Custom panel + +The `src/aem-assets-contenthub-1/web-src/src/components/PanelAssetDetailsExtensionTab.js` component is responsible for rendering the custom panel content. + +```js +import React, { useEffect, useState } from 'react'; +import { attach } from '@adobe/uix-guest'; +import { + Button, + ButtonGroup, + Flex, + Provider, + Text, + View, + defaultTheme +} from '@adobe/react-spectrum'; +import { extensionId } from './Constants'; + +export default function PanelAssetDetailsExtensionTab() { + const [guestConnection, setGuestConnection] = useState(); + + useEffect(() => { + (async () => { + const connection = await attach({ id: extensionId }); + setGuestConnection(connection); + })(); + }, []); + + function displayToast() { + guestConnection.host.toast.display({ + variant: 'neutral', + message: 'Message from the Extension' + }); + } + + return ( + + + Custom Content Hub panel + + + + + + + + ); +} +``` + +The `PanelAssetDetailsExtensionTab` establishes a connection with AEM Assets Content Hub using the `attach()` function. The React Spectrum `Provider` applies the default theme to the panel content. + +The `displayToast()` function displays a fixed toast message when the user clicks the button. + +For more information about `register()`, `attach()`, and the common host APIs, see [Common Concepts in Creating Extensions](../api/commons/index.md). + +## Test in local environment + +From the extension project directory, run the following command: + +```shell +aio app run +``` + +This will deploy the actions to Adobe I/O Runtime while running the UI part on the local machine. + +```shell +➜ demo-extension-project % aio app run + create .vscode/launch.json + +No change to package.json was detected. No package manager install will be executed. + +To view your local application: + -> https://localhost:9080 +To view your deployed application in the Experience Cloud shell: + -> https://experience.adobe.com/?devMode=true#/custom-apps/?localDevUrl=https://localhost:9080 +press CTRL+C to terminate dev environment +``` + +Now your UI Extension is reachable via the URL displayed in the Terminal. You can test your UI Extension within Content Hub by adding the following URL parameters: + +- ext (extension): `ext=https://localhost:9080` +- devMode (development mode): `devMode=true` +- repo (Content Hub delivery repository): `repo=delivery-pxxx-eyyy.adobeaemcloud.com` + +**Sample AEM Assets Content Hub URL:** `https://experience.adobe.com/?devMode=true&ext=https://localhost:9080&repo=delivery-p12345-e167890.adobeaemcloud.com#/assets/contenthub/` + +You may have to accept the self-signed certificate as described in the [Troubleshooting](../debug/index.md#accept-the-certificate) section. + +## Run on Stage + +After the development is completed, we can test our application on `Stage` before deploying to `Production`. For this we will use the `Stage` workspace in Adobe Developer Console. + +First, make sure you are logged in to the proper organization and using the `Stage` workspace: + +```shell +$ aio where + +You are currently in: +1. Org: Alpha Org +2. Project: ContentHubExtension +3. Workspace: Stage +``` + +After that, we build and deploy the frontend files and assets: + +```shell +aio app deploy + ✔ Building web assets for 'aem/assets/contenthub/1' + ✔ Deploying web assets for 'aem/assets/contenthub/1' +To view your deployed application: + -> https://123456-yournamespace-stage.adobeio-static.net/index.html +``` + +You can use the staging deployment URL (`https://123456-yournamespace-stage.adobeio-static.net/index.html` in this example) to test the extension with Content Hub by passing this URL to the `ext=` URL parameter. + +```text +https://experience.adobe.com/?devMode=true&ext=https://123456-yournamespace-stage.adobeio-static.net/index.html&repo=delivery-p12345-e167890.adobeaemcloud.com#/assets/contenthub/ +``` + +To learn more about deployment, refer to the [Deployment Overview](https://developer.adobe.com/app-builder/docs/guides/deployment/). + +## Deploy on Production and create approval request + +After the application has been completed, tested locally, and on `Stage`: we are ready to deploy it to `Production`. Refer to the [UI Extensions Development Flow](https://developer.adobe.com/uix/docs/guides/development-flow/#deploy-on-production) to learn how to do this. + +Also in this document you can find the whole development flow of a UI Extensions. + +## Additional resources + +- [AEM Assets Content Hub Extension Points](../api/index.md) +- [Code Generation](../code-generation/index.md) +- [UI Extensions Development Flow](../../../guides/development-flow/index.md) +- [Troubleshooting](../debug/index.md) +- [FAQ](../../../getting-started/faq/index.md) \ No newline at end of file diff --git a/src/pages/services/aem-assets-content-hub/index.md b/src/pages/services/aem-assets-content-hub/index.md new file mode 100644 index 00000000..5fd57c98 --- /dev/null +++ b/src/pages/services/aem-assets-content-hub/index.md @@ -0,0 +1,18 @@ +--- +title: Overview - AEM Assets Content Hub Extensibility +description: Learn how to extend AEM Assets Content Hub with custom user interface components and actions. +contributors: + - https://github.com/AdobeDocs/uix +--- + +# AEM Assets Content Hub Overview + +[AEM Assets Content Hub](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/assets/content-hub/product-overview) provides a branded portal for teams to discover, use, and distribute approved digital assets. It offers an intuitive interface designed for broader access to governed assets, with a focus on search, collections, sharing, and download. + +UI Extensibility allows third-party developers to extend and customize AEM Assets Content Hub with a modern front-end technology stack using JavaScript, Node.js, and React. + +AEM Assets Content Hub exposes a single, unified extension point, `aem/assets/contenthub/1`, that lets one extension add a custom panel to Asset Details, actions to Asset Cards and Collection Cards, and actions to the Selection Bar. In this section, you will find the available [extension point](api/index.md) and examples of how to use it. + + + +Start development with the [AEM Assets Content Hub sample application](https://github.com/adobe/aem-uix-examples/tree/main/aem-assets-contenthub-sample), follow the [step-by-step development guide](extension-development/index.md), and review [troubleshooting guidance](debug/index.md). \ No newline at end of file