|
| 1 | +--- |
| 2 | +title: AEM Assets View Extensibility |
| 3 | +description: Learn how to customize AEM Assets View |
| 4 | +contributors: |
| 5 | + - https://github.com/AdobeDocs/uix |
| 6 | +--- |
| 7 | + |
| 8 | +# Common Concepts in Creating Extensions |
| 9 | + |
| 10 | +Understand the fundamentals required to develop an extension for the AEM Assets View. |
| 11 | + |
| 12 | +## Extension Point |
| 13 | + |
| 14 | +AEM Assets View has an `aem/assets/details/1` [extension point](https://developer.adobe.com/app-builder/docs/guides/extensions/) |
| 15 | +that allows you to extend its functionality in the Details View. |
| 16 | +To declare it to be used by your extension, you need to add the following configuration to your `app.config.yaml` at the |
| 17 | +root of your extension: |
| 18 | + |
| 19 | +```yaml |
| 20 | +extensions: |
| 21 | + aem/assets/details/1: |
| 22 | + $include: src/aem-assets-details-1/ext.config.yaml |
| 23 | +``` |
| 24 | +Here is an example of `ext.config.yaml` file: |
| 25 | + |
| 26 | +```yaml |
| 27 | +operations: |
| 28 | + view: |
| 29 | + - type: web |
| 30 | + impl: index.html |
| 31 | +actions: actions |
| 32 | +web: web-src |
| 33 | +``` |
| 34 | + |
| 35 | +More **extension points** may be added in future releases to add extensibility features to other parts of the AEM Assets View. |
| 36 | + |
| 37 | +## Extension Registration |
| 38 | + |
| 39 | +Interaction between UI Extension and AEM Assets View starts with the initialization process that includes extension's |
| 40 | +capabilities registration so AEM Assets View knows when to invoke the extension and which APIs to expose. Registration is done by calling the `register()` |
| 41 | +function provided by `@adobe/uix-guest` library. This asynchronous function takes single object that describes extension |
| 42 | +and returns an object representing connection to the AEM Assets View. |
| 43 | + |
| 44 | +The `register()` function should be invoked after extension initialization page is loaded. |
| 45 | + |
| 46 | +Extension registration data must include: |
| 47 | + |
| 48 | +- `id` - string with random extension identifier. This identifier is useful for debugging of interaction between AEM Assets |
| 49 | +View and extension and is needed if extension provides custom UI. |
| 50 | +- `methods` - objects with the extension APIs exposed to the AEM Assets View. All methods are grouped into |
| 51 | +**namespaces** that represent more granular areas of AEM Assets View functionality within the extension point. |
| 52 | +Currently, only the following **namespace** is available: |
| 53 | + - `detailSidePanel`, that allows to add custom side panels in the Details View |
| 54 | + |
| 55 | +More **namespaces** may be added in future releases to add more extensibility features within the Details View. |
| 56 | + |
| 57 | +```js |
| 58 | +import { register } from "@adobe/uix-guest"; |
| 59 | +
|
| 60 | +// ... |
| 61 | +
|
| 62 | + const guestConnection = await register({ |
| 63 | + id: "extension-id", |
| 64 | + methods: { |
| 65 | + detailSidePanel: { |
| 66 | + getPanels() { |
| 67 | + // .. |
| 68 | + } |
| 69 | + }, |
| 70 | + } |
| 71 | + }); |
| 72 | +// ... |
| 73 | +``` |
| 74 | +## Building Extension UI |
| 75 | + |
| 76 | +The `aem/assets/details/1` extension point and its `detailSidePanel` **namespace** requires UI extension to provide |
| 77 | +its own interface for the custom side panel. This interface should be implemented as a separate entry point within the extension |
| 78 | +web application. |
| 79 | + |
| 80 | +Normally this interface needs data from the AEM Assets View or needs to trigger certain action within the host application. |
| 81 | +To support this the interface page should establish its own connection with AEM Assets View using the `attach()` function |
| 82 | +provided by `@adobe/uix-guest` library. |
| 83 | + |
| 84 | +In this example, the interface page establishes a connection with the AEM Assets View using extension `id` and obtains |
| 85 | +the AEM host URL: |
| 86 | + |
| 87 | +```js |
| 88 | +import { attach } from "@adobe/uix-guest"; |
| 89 | +
|
| 90 | +const guestConnection = await attach({ id: "extension-id" }); |
| 91 | +const aemHost = await guestConnection.discovery.getAemHost(); |
| 92 | +``` |
| 93 | + |
| 94 | +## Set up communication with AEM Assets View |
| 95 | + |
| 96 | +Both `register()` and `attach()` functions of `@adobe/uix-guest` library return the same connection object that has `host` property and |
| 97 | +exposes AEM Assets View API to UI Extensions. Through this API you can access data from the host application as well as |
| 98 | +invoke certain actions within it. |
| 99 | + |
| 100 | +## Common APIs exposed by AEM Assets View to all UI Extensions |
| 101 | + |
| 102 | +The APIs documented below are available to all AEM Assets View UI Extensions, irrespective of the extension point they are using. |
| 103 | + |
| 104 | +Every API is defined under its own namespace, which in turn is contained within the `host` object of the connection instance. |
| 105 | + |
| 106 | +All API invocations are asynchronous and return a `Promise`. |
| 107 | + |
| 108 | +### Authentication API |
| 109 | + |
| 110 | +This API provides information about the current Org, access token and API key in the AEM Assets View. |
| 111 | +The API uses `auth` namespace. |
| 112 | + |
| 113 | +`auth.getIMSInfo()` |
| 114 | + |
| 115 | +**Description:** returns information about IMS Org name, Id and access token. |
| 116 | + |
| 117 | +**Return Object Structure** |
| 118 | +- `imsOrg` (`string`): The IMS organization identifier. |
| 119 | +- `imsOrgName` (`string`): The name of the IMS organization. |
| 120 | +- `accessToken` (`string`): The access token for the IMS. |
| 121 | + |
| 122 | +`auth.getApiKey()` |
| 123 | + |
| 124 | +**Description:** returns API key used by the AEM Assets View. |
| 125 | + |
| 126 | +**Returns** (`string`): API key |
| 127 | + |
| 128 | +**Example:** |
| 129 | +```js |
| 130 | +const { imsOrg, accessToken } = await guestConnection.host.auth.getIMSInfo(); |
| 131 | +
|
| 132 | +const apiKey = await guestConnection.host.auth.getAPIKey(); |
| 133 | +``` |
| 134 | + |
| 135 | +### Discovery API |
| 136 | + |
| 137 | +This API provides information AEM author instance location. |
| 138 | + |
| 139 | +`discovery.getAemHost()` |
| 140 | + |
| 141 | +**Description:** returns the URL of the AEM author instance. |
| 142 | + |
| 143 | +**Returns** (`string`): AEM author instance URL |
| 144 | + |
| 145 | +**Example:** |
| 146 | +```js |
| 147 | +const aemHost = await guestConnection.host.discovery.getAemHost(); |
| 148 | +``` |
| 149 | + |
| 150 | +### Toast API |
| 151 | + |
| 152 | +This API provides methods to show toast messages in the AEM Assets View. |
| 153 | + |
| 154 | +`toast.display({ variant, message })` |
| 155 | + |
| 156 | +**Description:** shows a toast message in the AEM Assets View. |
| 157 | + |
| 158 | +**Parameters:** |
| 159 | +- **options** (`object`): Object with the following properties: |
| 160 | + - variant (`string`, optional): The type of toast message. Possible values are `neutral`, `positive`, `info`, `negative`. Default value is `info`. |
| 161 | + - message (`string`, required): The message to display in the toast. |
| 162 | + |
| 163 | +**Example:** |
| 164 | +```js |
| 165 | +guestConnection.host.toast.display({ variant: "positive", message: "Asset saved successfully" }); |
| 166 | +``` |
| 167 | + |
| 168 | +### Router API |
| 169 | + |
| 170 | +This API provides methods to navigate to different parts of the AEM Assets View. |
| 171 | + |
| 172 | +`router.navigateToAssetDetails({ assetPath })` |
| 173 | + |
| 174 | +**Description:** navigates to a Details View of the specific asset. |
| 175 | + |
| 176 | +**Parameters:** |
| 177 | +- **options** (`object`): Object with the following properties: |
| 178 | + - assetPath (`string`, required): The path to the asset in the AEM Assets View. |
| 179 | + |
| 180 | +**Example:** |
| 181 | +```js |
| 182 | +guestConnection.host.router.navigateToAssetDetails({ assetPath: '/content/dam/my-assets/image.jpg' }); |
| 183 | +``` |
| 184 | +### i18n API |
| 185 | + |
| 186 | +This API provides methods to support localization of the UI Extension. |
| 187 | + |
| 188 | +`i18n.getLocalizationInfo()` |
| 189 | + |
| 190 | +**Description:** returns information about the current locale used in the AEM Assets View. |
| 191 | + |
| 192 | +**Return Object Structure** |
| 193 | +- `locale` (`string`): The current locale used in the AEM Assets View. |
| 194 | + |
| 195 | +**Example:** |
| 196 | +```js |
| 197 | +const { locale } = await guestConnection.host.i18n.getLocalizationInfo(); |
| 198 | +``` |
0 commit comments