Skip to main content
Platform
Language

Manage Assets

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to manage assets through the asset API.

To begin working with assets first you need at least one asset source. As the name might imply asset sources provide the engine with assets. These assets then show up in the editor's asset library. But they can also be independently searched and used to create design blocks. Asset sources can be added dynamically using the asset API as we will show in this guide.

Setup#

This example uses the headless CreativeEngine. See the Setup article for a detailed guide. To get started right away, you can also access the block API within a running CE.SDK instance via cesdk.engine.block. Check out the APIs Overview to see that illustrated in more detail.

Defining a Custom Asset Source#

Asset sources need at least an id and a findAssets function. You may notice asset source functions are all async. This way you can use web requests or other long-running operations inside them and return results asynchronously.

Let's go over these properties one by one:

All functions of the asset API refer to an asset source by its unique id. That's why it has to be mandatory. Trying to add an asset source with an already registered id will fail.

Finding and Applying Assets#

The findAssets function should return paginated asset results for the given queryData. The asset results have a set of mandatory and optional properties. For a listing with an explanation for each property please refer to the Integrate a Custom Asset Source guide. The properties of the queryData and the pagination mechanism are also explained in this guide.

findAssets(sourceId: string, query: AssetQueryData): Promise<AssetsQueryResult<CompleteAssetResult>>

Finds assets of a given type in a specific asset source.

  • sourceId: The ID of the asset source.
  • query: All the options to filter the search results by.
  • Returns The search results.

The optional function 'applyAsset' is to define the behavior of what to do when an asset gets applied to the scene. You can use the engine's APIs to do whatever you want with the given asset result. In this case, we always create an image block and add it to the first page we find.

If you don't provide this function the engine's default behavior is to create a block based on the asset result's meta.blockType property, add the block to the active page, and sensibly position and size it.

apply(sourceId: string, assetResult: AssetResult): Promise<DesignBlockId | undefined>

Apply an asset result to the active scene. The default behavior will instantiate a block and configure it according to the asset's properties. Note that this can be overridden by providing an applyAsset function when adding the asset source.

  • sourceId: The ID of the asset source.
  • assetResult: A single assetResult of a findAssets query.
defaultApplyAsset(assetResult: AssetResult): Promise<DesignBlockId | undefined>

The default implementation for applying an asset to the scene. This implementation is used when no applyAsset function is provided to addSource.

  • assetResult: A single assetResult of a findAssets query.
applyToBlock(sourceId: string, assetResult: AssetResult, block: DesignBlockId): Promise<void>

Apply an asset result to the given block.

  • sourceId: The ID of the asset source.
  • assetResult: A single assetResult of a findAssets query.
  • block: The block the asset should be applied to.
defaultApplyAssetToBlock(assetResult: AssetResult, block: DesignBlockId): Promise<void>

The default implementation for applying an asset to an existing block.

  • assetResult: A single assetResult of a findAssets query.
  • block: The block to apply the asset result to.
getSupportedMimeTypes(sourceId: string): string[]

Queries the list of supported mime types of the specified asset source. An empty result means that all mime types are supported.

  • sourceId: The ID of the asset source.

Registering a New Asset Source#

addSource(source: AssetSource): void

Adds a custom asset source. Its ID has to be unique.

  • source: The asset source.
addLocalSource(id: string, supportedMimeTypes?: string[], applyAsset?: (asset: CompleteAssetResult) => Promise<DesignBlockId | undefined>, applyAssetToBlock?: (asset: CompleteAssetResult, block: DesignBlockId) => Promise<void>): void

Adds a local asset source. Its ID has to be unique.

  • source: The asset source.
  • supportedMimeTypes: The mime types of assets that are allowed to be added to this local source.
  • applyAsset: An optional callback that can be used to override the default behavior of applying a given asset result to the active scene.
  • applyAssetToBlock: An optional callback that can be used to override the default behavior of applying an asset result to a given block.
findAllSources(): string[]

Finds all registered asset sources.

  • Returns A list with the IDs of all registered asset sources.
removeSource(id: string): void

Removes an asset source with the given ID.

  • id: The ID to refer to the asset source.
onAssetSourceAdded: (callback: (sourceID: string) => void) => (() => void)

Register a callback to be called every time an asset source is added.

  • callback: The function that is called whenever an asset source is added.
  • Returns A method to unsubscribe.
onAssetSourceRemoved: (callback: (sourceID: string) => void) => (() => void)

Register a callback to be called every time an asset source is removed.

  • callback: The function that is called whenever an asset source is added.
  • Returns A method to unsubscribe.
onAssetSourceUpdated: (callback: (sourceID: string) => void) => (() => void)

Register a callback to be called every time an asset source's contents are changed.

  • callback: The function that is called whenever an asset source is updated.
  • Returns A method to unsubscribe.

Scene Asset Sources#

A scene colors asset source is automatically available that allows listing all colors in the scene. This asset source is read-only and is updated when findAssets is called.

Add an Asset#

addAssetToSource(sourceId: string, asset: AssetDefinition): void

Adds the given asset to a local asset source.

  • sourceId: The local asset source ID that the asset should be added to.
  • asset: The asset to be added to the asset source.

Remove an Asset#

removeAssetFromSource(sourceId: string, assetId: string): void

Removes the specified asset from its local asset source.

  • sourceId: The id of the local asset source that currently contains the asset.
  • assetId: The id of the asset to be removed.

Asset Source Content Updates#

If the contents of your custom asset source change, you can call the assetSourceUpdated API to later notify all subscribers of the onAssetSourceUpdated API.

assetSourceContentsChanged(sourceID: string): void

Notifies the engine that the contents of an asset source changed.

  • sourceID: The asset source whose contents changed.

Groups in Assets#

getGroups(id: string): Promise<string[]>

Queries the asset source's groups for a certain asset type.

  • id: The ID of the asset source.
  • Returns The asset groups.

Credits and License#

getCredits(sourceId: string): {
name: string;
url: string | undefined;
} | undefined

Queries the asset source's credits info.

  • sourceId: The ID of the asset source.
  • Returns The asset source's credits info consisting of a name and an optional URL.
getLicense(sourceId: string): {
name: string;
url: string | undefined;
} | undefined

Queries the asset source's license info.

  • sourceId: The ID of the asset source.
  • Returns The asset source's license info consisting of a name and an optional URL.