How to Store Custom Metadata

CE.SDK allows you to store custom metadata in your scenes. You can attach metadata to your scene or directly to your individual design blocks within the scene. This metadata is persistent across saving and loading of scenes. It simply consists of key value pairs of strings. Using any string-based serialization format such as JSON will allow you to store even complex objects. Please note that when duplicating blocks their metadata will also be duplicated.

Explore a full code sample on Stackblitz or view the code on Github.

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.

Working with Metadata#

We can add metadata to any design block using setMetadata(block: number, key: string, value: string). This also includes the scene block.

We can retrieve metadata from any design block or scene using getMetadata(block: number, key: string): string. Before accessing the metadata you check for its existence using hasMetadata(block: number, key: string): boolean.

We can query all metadata keys from any design block or scene using findAllMetadata(block: number): string[]. For blocks without any metadata, this will return an empty list.

If you want to get rid of any metadata, you can use removeMetadata(block: number, key: string).

Metadata will automatically be saved and loaded as part the scene. So you don't have to worry about it getting lost or having to save it separately.


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

const config = {
  license: 'mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm',
  userId: 'guides-user',
  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.24.0/assets'
};

CreativeEngine.init(config).then(async (engine) => {
  let scene = await engine.scene.createFromImage(
    'https://img.ly/static/ubq_samples/imgly_logo.jpg'
  );
  // get the graphic block with the image fill
  // Note: In this example we know that the first block since there is only one block in the scene
  // at this point. You might need to filter by fill type if you have multiple blocks.
  const block = engine.block.findByType('graphic')[0];

  engine.block.setMetadata(scene, 'author', 'img.ly');
  engine.block.setMetadata(block, 'customer_id', '1234567890');

  /* We can even store complex objects */
  const payment = {
    id: 5,
    method: 'credit_card',
    received: true
  };
  engine.block.setMetadata(block, 'payment', JSON.stringify(payment));

  /* This will return 'img.ly' */
  engine.block.getMetadata(scene, 'author');

  /* This will return '1000000' */
  engine.block.getMetadata(block, 'customer_id');

  /* This will return ['customer_id'] */
  engine.block.findAllMetadata(block);

  engine.block.removeMetadata(block, 'payment');

  /* This will return false */
  engine.block.hasMetadata(block, 'payment');

  /* We save our scene and reload it from scratch */
  const sceneString = await engine.scene.saveToString();
  scene = await engine.scene.loadFromString(sceneString);

  /* This still returns 'img.ly' */
  engine.block.getMetadata(scene, 'author');

  /* And this still returns '1234567890' */
  engine.block.getMetadata(block, 'customer_id');

  // Attach engine canvas to DOM
  document.getElementById('cesdk_container').append(engine.element);
});