Assets in Uniform
The asset parameter and asset field each provide a seamless interface for adding media into a composition or content entry. The parameter can be configured to support multiple asset selection. Each asset may be from a different source. All assets have standard fields where you can add context-specific content, or connect to an external data source like a CMS or e-commerce system.
tip
For details on adding the asset parameter to a component, refer to the parameter guide. To add assets to a content type, refer to the field guide.
Asset sources#
There are three ways to connect to an asset:
- Through a library
- From an existing data resource
- Via a custom URL
Libraries#
Integrations offer a large collection of assets and should be used to serve them across multiple compositions or channels. Uniform has a lightweight asset library, available for storing assets.
Data resources#
You can select assets from any existing data resource. This is useful to select an image from the current product entry used to assemble a product detail page in Canvas.
Custom URL#
Selecting this option provides a way to create an inline link to an image URL hosted elsewhere.
Select an asset#
How to select an asset depends on the source of the asset. Once added, a preview of the image is shown and the current asset count updates.
info
The ability to select more than one asset depends on how you configure the parameter. You may need to remove an asset before being able to add a new one.
Asset properties#
The asset parameter provides a composition with a set of properties about an asset, reducing or eliminating the need to model them as separate component parameters. The following properties can be edited either in Uniform or your application. You can choose to use only a subset of the properties. The only required property is the image URL, or source. Learn about asset utilities provided by the Uniform SDK.
| Field | Availability |
|---|---|
| Alt | Alt text ensures the image is accessible to all users and is used by search engines. |
| URL | This field represents the location of the binary file. Once created, it can't be changed. In your application, this may be called src. |
| Width | The width of the image |
| Height | The height of the image |
Public API properties#
The data within the asset parameter is returned as an array, even if the array only contains one item. API responses include these fields:
| Field | Required | User editable | Image type expected usage |
|---|---|---|---|
| Type | Yes | No | Image |
| Source | Yes | No | This is an internal field indicating the source of the image. It could be an integration id, a data resource name or custom |
| Title | No | Yes | This is expected to be used in the alt attribute and describe the image. |
| URL | Yes | Yes | This is expected to be used in the src attribute of an image tag, and the default location of the image. This is a general URL where the size of the image should be appropriate to the context. This isn't designed to support multiple variants for the picture element or srcset. To support responsive variants you would need to construct them based on this URL or other properties in the response. |
| Description | No | Yes | This is a longer description of the image. It would be a good use for a caption. |
| ID | No | No | A unique identifier for the image |
| Media Type | No | No | The media type of the original image, formerly known as MIME type. |
| Size | No | No | The file size in bytes. |
| Width | No | No | The width of the original image |
| Height | No | No | The height of the original image |
| Custom | No | No | A place for structured data which can be used by an integration to add extra details to the parameter or field. |
In the context of a composition, the response from the API would be structured like this:
Manage your selection#
Once you have added an image to the asset parameter in a composition, you can:
- Reorder assets: You can reorder assets by dragging and dropping them within the property panel of Canvas. This will change the order of items in the array in which they're delivered through the APIs.
- Remove: If you click on an item in the property panel, it will open in it in a modal. Clicking "remove from selection" will remove the asset from the selection. The uploaded file and asset record (if applicable) won't be deleted. However, any customization of any properties will be lost.
info
When you edit an asset property from within a composition, you will override the information coming from the asset. Those changes aren't written back to the asset's source, like the asset library. The changes remain specific to the usage within the composition. If you edit the asset at the source, such as in the asset library, those changes will be present wherever the asset is used throughout the project.