From Scene File - Angular

CE.SDK lets you load complete design templates from scene files to start projects from pre-designed templates, implement template galleries, and build template management systems.

Import Templates from Scene Files example showing CE.SDK interface with loaded template

10 mins

estimated time

Download

StackBlitz

GitHub

Scene files are portable design templates that preserve the entire design structure including blocks, assets, styles, and layout.

import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
import {
  BlurAssetSource,
  ImageColorsAssetSource,
  ColorPaletteAssetSource,
  CropPresetsAssetSource,
  DemoAssetSources,
  EffectsAssetSource,
  FiltersAssetSource,
  PagePresetsAssetSource,
  StickerAssetSource,
  TextAssetSource,
  TextComponentAssetSource,
  TypefaceAssetSource,
  UploadAssetSources,
  VectorShapeAssetSource
} from '@cesdk/cesdk-js/plugins';
import { DesignEditorConfig } from '@cesdk/core-configs-web/design-editor';
import packageJson from './package.json';

/**
 * CE.SDK Plugin: Import Templates from Scene Files
 *
 * This example demonstrates:
 * - Loading scenes from .scene file URLs
 * - Loading scenes from .archive (ZIP) URLs
 * - Applying templates while preserving page dimensions
 * - Understanding the difference between loading and applying templates
 */
class Example implements EditorPlugin {
  name = packageJson.name;
  version = packageJson.version;

  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
    if (!cesdk) {
      throw new Error('CE.SDK instance is required for this plugin');
    }

    await cesdk.addPlugin(new DesignEditorConfig());
    // Add asset source plugins
    await cesdk.addPlugin(new BlurAssetSource());
    await cesdk.addPlugin(new ImageColorsAssetSource());
    await cesdk.addPlugin(new ColorPaletteAssetSource());
    await cesdk.addPlugin(new CropPresetsAssetSource());
    await cesdk.addPlugin(
      new UploadAssetSources({ include: ['ly.img.image.upload'] })
    );
    await cesdk.addPlugin(
      new DemoAssetSources({
        include: [
          'ly.img.templates.blank.*',
          'ly.img.templates.presentation.*',
          'ly.img.templates.print.*',
          'ly.img.templates.social.*',
          'ly.img.image.*'
        ]
      })
    );
    await cesdk.addPlugin(new EffectsAssetSource());
    await cesdk.addPlugin(new FiltersAssetSource());
    await cesdk.addPlugin(new PagePresetsAssetSource());
    await cesdk.addPlugin(new StickerAssetSource());
    await cesdk.addPlugin(new TextAssetSource());
    await cesdk.addPlugin(new TextComponentAssetSource());
    await cesdk.addPlugin(new TypefaceAssetSource());
    await cesdk.addPlugin(new VectorShapeAssetSource());

    const engine = cesdk.engine;

    // ===== Example: Load Scene from Archive URL =====
    // This is the recommended approach for loading complete templates
    // with all their assets embedded in a ZIP file

    // Load a complete template from an archive file
    // This loads both the scene structure and all embedded assets
    await engine.scene.load(
      'https://cdn.img.ly/assets/templates/starterkits/16-9-fashion-ad.zip'
    );

    // Alternative: Load scene from URL (plain scene file)
    // This loads only the scene structure - assets must be accessible via URLs
    // Uncomment to try:
    // await engine.scene.load(
    //   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
    // );

    // Alternative: Apply template while preserving current page dimensions
    // This is useful when you want to load template content into an existing scene
    // with specific dimensions
    // Uncomment to try:
    // // First create a scene with specific dimensions
    // await cesdk.actions.run('scene.create', { page: { width: 1920, height: 1080, unit: 'Pixel' } });
    // const page = engine.block.findByType('page')[0];
    //
    // // Now apply template - content will be adjusted to fit
    // await engine.scene.applyTemplateFromURL(
    //   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_instagram_photo_1.scene'
    // );

    // Get the loaded scene
    const scene = engine.scene.get();
    if (scene) {
      console.log('Scene loaded successfully:', scene);

      // Get information about the loaded scene
      const pages = engine.scene.getPages();
      console.log(`Scene has ${pages.length} page(s)`);

      // Get design unit
      const designUnit = engine.scene.getDesignUnit();
      console.log('Design unit:', designUnit);
    }

    // Zoom to fit the loaded content
    if (scene) {
      await engine.scene.zoomToBlock(scene, {
        padding: 40
      });
    }
  }
}

export default Example;

This guide covers loading scenes from archives, loading from URLs, applying templates while preserving dimensions, and understanding scene file formats.

Scene File Formats#

CE.SDK supports two kinds of scene files for importing templates. Both use the .imgly extension and load through the same engine.scene.load() call, which detects the kind automatically from the file content; .scene and .zip files also load.

Scene Format#

Scene files are JSON-based representations of design structures. They reference external assets via URLs, making them lightweight and suitable for database storage. However, the referenced assets must remain accessible at their URLs.

When to use:

Templates stored in databases
Templates with hosted assets
Lightweight transmission

Archive Format#

Archive files are self-contained packages that bundle the scene structure with all referenced assets in a zip-compressed file. This makes them portable and suitable for offline use.

When to use:

Template distribution
Offline-capable templates
Complete portability
Recommended for most use cases

Load Scene from Archive#

The most common way to load templates is from archive URLs. This method loads both the scene structure and all embedded assets:

import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
import {
  BlurAssetSource,
  ImageColorsAssetSource,
  ColorPaletteAssetSource,
  CropPresetsAssetSource,
  DemoAssetSources,
  EffectsAssetSource,
  FiltersAssetSource,
  PagePresetsAssetSource,
  StickerAssetSource,
  TextAssetSource,
  TextComponentAssetSource,
  TypefaceAssetSource,
  UploadAssetSources,
  VectorShapeAssetSource
} from '@cesdk/cesdk-js/plugins';
import { DesignEditorConfig } from '@cesdk/core-configs-web/design-editor';
import packageJson from './package.json';

/**
 * CE.SDK Plugin: Import Templates from Scene Files
 *
 * This example demonstrates:
 * - Loading scenes from .scene file URLs
 * - Loading scenes from .archive (ZIP) URLs
 * - Applying templates while preserving page dimensions
 * - Understanding the difference between loading and applying templates
 */
class Example implements EditorPlugin {
  name = packageJson.name;
  version = packageJson.version;

  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
    if (!cesdk) {
      throw new Error('CE.SDK instance is required for this plugin');
    }

    await cesdk.addPlugin(new DesignEditorConfig());
    // Add asset source plugins
    await cesdk.addPlugin(new BlurAssetSource());
    await cesdk.addPlugin(new ImageColorsAssetSource());
    await cesdk.addPlugin(new ColorPaletteAssetSource());
    await cesdk.addPlugin(new CropPresetsAssetSource());
    await cesdk.addPlugin(
      new UploadAssetSources({ include: ['ly.img.image.upload'] })
    );
    await cesdk.addPlugin(
      new DemoAssetSources({
        include: [
          'ly.img.templates.blank.*',
          'ly.img.templates.presentation.*',
          'ly.img.templates.print.*',
          'ly.img.templates.social.*',
          'ly.img.image.*'
        ]
      })
    );
    await cesdk.addPlugin(new EffectsAssetSource());
    await cesdk.addPlugin(new FiltersAssetSource());
    await cesdk.addPlugin(new PagePresetsAssetSource());
    await cesdk.addPlugin(new StickerAssetSource());
    await cesdk.addPlugin(new TextAssetSource());
    await cesdk.addPlugin(new TextComponentAssetSource());
    await cesdk.addPlugin(new TypefaceAssetSource());
    await cesdk.addPlugin(new VectorShapeAssetSource());

    const engine = cesdk.engine;

    // ===== Example: Load Scene from Archive URL =====
    // This is the recommended approach for loading complete templates
    // with all their assets embedded in a ZIP file

    // Load a complete template from an archive file
    // This loads both the scene structure and all embedded assets
    await engine.scene.load(
      'https://cdn.img.ly/assets/templates/starterkits/16-9-fashion-ad.zip'
    );

    // Alternative: Load scene from URL (plain scene file)
    // This loads only the scene structure - assets must be accessible via URLs
    // Uncomment to try:
    // await engine.scene.load(
    //   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
    // );

    // Alternative: Apply template while preserving current page dimensions
    // This is useful when you want to load template content into an existing scene
    // with specific dimensions
    // Uncomment to try:
    // // First create a scene with specific dimensions
    // await cesdk.actions.run('scene.create', { page: { width: 1920, height: 1080, unit: 'Pixel' } });
    // const page = engine.block.findByType('page')[0];
    //
    // // Now apply template - content will be adjusted to fit
    // await engine.scene.applyTemplateFromURL(
    //   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_instagram_photo_1.scene'
    // );

    // Get the loaded scene
    const scene = engine.scene.get();
    if (scene) {
      console.log('Scene loaded successfully:', scene);

      // Get information about the loaded scene
      const pages = engine.scene.getPages();
      console.log(`Scene has ${pages.length} page(s)`);

      // Get design unit
      const designUnit = engine.scene.getDesignUnit();
      console.log('Design unit:', designUnit);
    }

    // Zoom to fit the loaded content
    if (scene) {
      await engine.scene.zoomToBlock(scene, {
        padding: 40
      });
    }
  }
}

export default Example;

// Load a complete template from an archive file
// This loads both the scene structure and all embedded assets
await engine.scene.load(
  'https://cdn.img.ly/assets/templates/starterkits/16-9-fashion-ad.zip'
);

When you load from an archive:

The archive is fetched and extracted
All assets are registered with CE.SDK
The scene structure is loaded
Asset paths are automatically resolved

Load Scene from URL#

You can also load plain scene files directly from URLs. This approach requires that all referenced assets remain accessible at their original URLs:

// await engine.scene.load(
//   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_postcard_1.scene'
// );

Important: With this method, if asset URLs become unavailable (404 errors, CORS issues, etc.), those assets won’t load and your template may appear incomplete.

Apply Template vs Load Scene#

CE.SDK provides two approaches for working with templates, each serving different purposes:

Load Scene#

When you use engine.scene.load(), CE.SDK:

Replaces the entire current scene
Adopts the template’s page dimensions
Loads all content as-is

This is appropriate when starting a new project from a template.

Apply Template#

When you use applyTemplateFromURL() or applyTemplateFromString(), CE.SDK:

Keeps your current page dimensions
Adjusts template content to fit
Preserves your scene structure

This is useful when you want to load template content into an existing scene with specific dimensions:

// // First create a scene with specific dimensions
// await cesdk.actions.run('scene.create', { page: { width: 1920, height: 1080, unit: 'Pixel' } });
// const page = engine.block.findByType('page')[0];
//
// // Now apply template - content will be adjusted to fit
// await engine.scene.applyTemplateFromURL(
//   'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_instagram_photo_1.scene'
// );

Error Handling#

When loading templates, several issues can occur:

Network Errors#

Template URLs might be unreachable:

try {
  await engine.scene.load(templateUrl);
} catch (error) {
  console.error('Failed to load template:', error);
  // Show error message to user
  // Fall back to default template or empty scene
}

Invalid Scene Format#

The file might not be a valid scene:

try {
  await engine.scene.load(sceneUrl);
} catch (error) {
  if (error.message.includes('parse')) {
    console.error('Invalid scene file format');
  }
}

Missing Assets#

For plain scene files, the referenced assets must remain accessible at their URLs. If they are unavailable, the scene loads but assets appear as missing on the canvas. Consider using archives to avoid this issue.

Performance Considerations#

Loading Time#

Archive size directly impacts loading time:

Small archives (< 1MB): Nearly instant
Medium archives (1-5MB): 1-2 seconds
Large archives (> 5MB): Several seconds

Show loading indicators for better user experience.

CORS Considerations#

When loading templates from external URLs, ensure proper CORS headers are set on the server hosting the files. Archives must be accessible with appropriate CORS policies.

API Reference#

Method	Description
`engine.scene.load()`	Loads a scene or archive from a URL or string
`engine.scene.applyTemplateFromURL()`	Applies a template while preserving page dimensions
`engine.scene.get()`	Returns the current scene block ID
`engine.scene.getPages()`	Returns all page IDs in the scene
`engine.scene.getDesignUnit()`	Returns the measurement unit
`engine.scene.zoomToBlock()`	Zooms the viewport to fit a specific block