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.

JavaScript


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.

JavaScript


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.

JavaScript


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.

JavaScript


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.

JavaScript


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.

JavaScript


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#

JavaScript


addSource(source: AssetSource): void

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

source: The asset source.

JavaScript


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.

JavaScript


findAllSources(): string[]

Finds all registered asset sources.

Returns A list with the IDs of all registered asset sources.

JavaScript


removeSource(id: string): void

Removes an asset source with the given ID.

id: The ID to refer to the asset source.

JavaScript


onAssetSourceAdded: (callback: (sourceID: string) => void) => (() => void)

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

JavaScript


onAssetSourceRemoved: (callback: (sourceID: string) => void) => (() => void)

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

JavaScript


onAssetSourceUpdated: (callback: (sourceID: string) => void) => (() => void)

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#

JavaScript


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#

JavaScript


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.

JavaScript


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#

JavaScript


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#

JavaScript


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.

JavaScript


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.


import CreativeEngine from 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.17.0/index.js';

const config = {
  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.17.0/assets'
};

CreativeEngine.init(config).then(async (engine) => {
  const scene = engine.scene.create();
  const page = engine.block.create('page');
  engine.block.appendChild(scene, page);

  const customSource = {
    id: 'foobar',
    async findAssets(queryData) {
      return Promise.resolve({
        assets: [
          {
            id: 'logo',
            meta: {
              uri: 'https://img.ly/static/ubq_samples/imgly_logo.jpg',
              thumbUri:
                'https://img.ly/static/ubq_samples/thumbnails/imgly_logo.jpg',
              blockType: '//ly.img.ubq/image',
              width: 320,
              height: 116
            },
            context: {
              sourceId: 'foobar'
            }
          }
        ],
        total: 1,
        currentPage: queryData.page,
        nextPage: undefined
      });
    },
    async applyAsset(assetResult) {
      return engine.asset.defaultApplyAsset(assetResult);
    },
    async applyAssetToBlock(assetResult, block) {
      engine.asset.defaultApplyAssetToBlock(assetResult, block);
    }
  };

  engine.asset.onAssetSourceAdded((sourceID) => {
    console.log(`Added source: ${sourceID}`);
  });
  engine.asset.onAssetSourceRemoved((sourceID) => {
    console.log(`Removed source: ${sourceID}`);
  });
  engine.asset.onAssetSourceUpdated((sourceID) => {
    console.log(`Updated source: ${sourceID}`);
  });

  engine.asset.addSource(customSource);

  engine.asset.addLocalSource('local-source');

  engine.asset.addAssetToSource('local-source', {
    id: 'ocean-waves-1',
    label: {
      en: 'relaxing ocean waves'
    },
    tags: {
      en: ['ocean', 'waves', 'soothing', 'slow']
    },
    meta: {
      uri: `https://example.com/ocean-waves-1.mp4`,
      thumbUri: `https://example.com/thumbnails/ocean-waves-1.jpg`,
      mimeType: 'video/mp4',
      width: 1920,
      height: 1080
    }
  });
  engine.asset.removeAssetFromSource('local-source', 'ocean-waves-1');

  engine.asset.removeSource('local-source');

  engine.asset.findAllSources();

  const mimeTypes = engine.asset.getSupportedMimeTypes(
    'ly.img.asset.source.unsplash'
  );

  const credits = engine.asset.getCredits(customSource.id);
  const license = engine.asset.getLicense(customSource.id);
  const groups = engine.asset.getGroups(customSource.id);

  const result = await engine.asset.findAssets(customSource.id, {
    page: 0,
    perPage: 100
  });
  const asset = result.assets[0];
  const sortByNewest = await engine.asset.findAssets('ly.img.image.upload', {
    page: 0,
    perPage: 10,
    sortingOrder: 'Descending'
  });
  const sortById = await engine.asset.findAssets('ly.img.image.upload', {
    page: 0,
    perPage: 10,
    sortingOrder: 'Ascending',
    sortKey: 'id'
  });
  const sortByMetaKeyValue = await engine.asset.findAssets(
    'ly.img.image.upload',
    {
      page: 0,
      perPage: 10,
      sortingOrder: 'Ascending',
      sortKey: 'someMetaKey'
    }
  );
  const search = await engine.asset.findAssets('ly.img.asset.source.unsplash', {
    query: 'banana',
    page: 0,
    perPage: 100
  });

  const sceneColorsResult = await engine.asset.findAssets(
    'ly.img.scene.colors',
    {
      page: 0,
      perPage: 99999
    }
  );
  const colorAsset = sceneColorsResult.assets[0];

  await engine.asset.apply(customSource.id, asset);

  await engine.asset.applyToBlock(customSource.id, asset);

  engine.asset.assetSourceContentsChanged(customSource.id);

  // highlight-removeSource
  engine.asset.removeSource(customSource.id);

  document.getElementById('cesdk_container').append(engine.element);
});