Interacting with the Scene using the CreativeEditor SDK Engine

A block (or design block) is the main building unit in CE.SDK. Blocks are organized in a hierarchy through parent-child relationships. A scene is a specialized block that acts as the root of this hierarchy. Commonly, a scene contains several pages which in turn contain any other blocks such as images and texts.

In this example, we want to show you how to create and modify a scene and its blocks in CE.SDK.

Explore a full code sample of the integration on CodeSandbox or view the code on GitHub.

Creating or Using an Existing Scene#

When using the Engine's API in the context of the CE.SDK editor, there's already an existing scene. You can obtain a handle to this scene by calling the SceneAPI's scene.get(): number method. However, when using the Engine on its own you first have to create a scene, e.g. using scene.create(): number. See the Creating Scenes guide for more details and options.

Next, we need a page to place our blocks on. The scene automatically arranges its pages either in a vertical (the default) or horizontal layout. Again in the context of the editor, there's already an existing page. To fetch that page call the BlockAPI's block.findByType(type: string): number[] method and use the first element of the returned array.

When only using the engine, you have to create a page yourself and append it to the scene. To do that create the page using block.create(type: string): number and append it to the scene with block.appendChild(parent: number, child: number).

At this point, you should have a handle to an existing scene as well as a handle to its page. Now it gets interesting when we start to add different types of blocks to the scene's page.

Modifying the Scene#

As an example, we create an image block using the BlockAPI's create() method which we already used for creating our page. To see what other kinds of blocks are available see the Block Types in the API Reference.

We set a couple of properties of our newly created image by giving it a URL to reference an image file from and make sure the entire image stays visible by setting its content fill mode to 'Contain'. To learn more about block properties check out the Block Properties API Reference.

And finally, for our image to be visible we have to add it to our page using appendChild.

To frame everything nicely and put it into view we direct the scene's camera to zoom on our page.

File:

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

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

CreativeEngine.init(config, document.getElementById('cesdk_canvas')).then(
  (instance) => {
    let scene = instance.scene.get();
    /* In engine only mode we have to create our own scene and page. */
    if (!scene) {
      scene = instance.scene.create();
      const page = instance.block.create('page');
      instance.block.appendChild(scene, page);
    }
    /* Find all pages in our scene. */
    const pages = instance.block.findByType('page');
    /* Use the first page we found. */
    const page = pages[0];

    /* Create an image block and add it to the scene's page. */
    const image = instance.block.create('image');

    instance.block.setString(
      image,
      'image/imageFileURI',
      'https://img.ly/static/ubq_samples/imgly_logo.jpg'
    );
    /* The content fill mode 'Contain' ensures the entire image is visible. */
    instance.block.setEnum(image, 'contentFill/mode', 'Contain');

    instance.block.appendChild(page, image);

    /* Zoom the scene's camera on our page. */
    instance.scene.zoomToBlock(page);
  }
);