Observe Events

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to subscribe to creation, update, and destruction events of design blocks.

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.

Subscribing to Events#

The event API provides a single function to subscribe to design block events. The types of events are:

'Created': The design block was just created.
'Updated': A property of the design block was updated.
'Destroyed': The design block was destroyed. Note that a destroyed block will have become invalid and trying to use Block API functions on it will result in an exception. You can always use the Block API's isValid function to verify whether a block is valid before use.

All events that occur during an engine update are batched, deduplicated, and always delivered at the very end of the engine update. Deduplication means you will receive at most one 'Updated' event per block per subscription, even though there could potentially be multiple updates to a block during the engine update. To be clear, this also means the order of the event list provided to your event callback won't reflect the actual order of events within an engine update.

subscribe(blocks: number[], callback: (events: {type: string, block: number}[]) => void): () => void
subscribe to events from a given list of blocks. Providing an empty list will subscribe to events from all of the engine's blocks. The provided callback will receive a list of events that occurred in the last engine update. Each event consists of the event type and the affected block. The returned function shall be used to unsubscribe from receiving further events.

Unsubscribing from events#

subscribe returns a function that can be called to unsubscribe from receiving events.

Note that it is important to unsubscribe when done. At the end of each update the engine has to prepare a list of events for each individual subscriber. Unsubscribing will help to reduce unnecessary work and improve performance.


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

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

CreativeEngine.init(config).then(async (engine) => {
  document.getElementById('cesdk_container').append(engine.element);

  const scene = engine.scene.create();
  const page = engine.block.create('page');
  engine.block.appendChild(scene, page);

  const block = engine.block.create('graphic');
  engine.block.setShape(block, engine.block.createShape('star'));
  engine.block.setFill(block, engine.block.createFill('color'));
  engine.block.appendChild(page, block);

  let unsubscribe = engine.event.subscribe([block], (events) => {
    for (var i = 0; i < events.length; i++) {
      let event = events[i];
      console.log('Event:', event.type, event.block);
      if (engine.block.isValid(event.block)) {
        console.log('Block type:', engine.block.getType(event.block));
      }
    }
  });

  await sleep(1000);
  engine.block.setRotation(block, 0.5 * Math.PI);
  await sleep(1000);
  engine.block.destroy(block);
  await sleep(1000);

  unsubscribe();

  function sleep(ms) {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }
});