Search
Loading...
Skip to content

Apply a Template

Apply template content to an existing scene while preserving your canvas dimensions and design unit.

5 mins
estimated time
Download
StackBlitz
GitHub

Unlike loading a scene which replaces everything, applying a template merges template content into your current scene. CE.SDK preserves the current page dimensions and design unit while automatically adjusting template content to fit. This approach is ideal for automation pipelines that standardize output sizes across varying template sources, or batch processing workflows that need consistent export dimensions.

This guide covers how to apply templates from URLs while preserving page dimensions, export results with consistent sizes, and implement template switching in headless workflows.

When to Use Apply vs Load#

Use applyTemplateFromURL() or applyTemplateFromString() when you want to:

  • Standardize output dimensions: Generate content with fixed sizes (e.g., social media formats, print sizes)
  • Batch process with templates: Apply various templates to a pre-configured scene without dimension drift
  • Switch templates: Iterate through templates while keeping consistent export dimensions

Use loadFromString() or loadFromURL() when you need the template’s original dimensions.

Key distinction: Loading replaces everything; applying preserves dimensions and merges content.

Initialize the Engine#

We start by initializing the headless engine.

const config = {
  // license: process.env.CESDK_LICENSE,
  logger: (message: string, logLevel?: string) => {
    if (logLevel === 'ERROR' || logLevel === 'WARN') {
      console.log(`[${logLevel}]`, message);
    }
  }
};


engine = await CreativeEngine.init(config);
console.log('✓ Engine initialized');

Create a Scene with Target Dimensions#

We create a scene with specific dimensions. These dimensions will be preserved when we apply templates and determine the final export size.

// Create a scene with specific dimensions
// These dimensions will be preserved when applying templates
const scene = engine.scene.create();
const page = engine.block.create('page');
engine.block.appendChild(scene, page);


// Set custom dimensions for fixed output size (e.g., social media post)
engine.block.setWidth(page, 1080);
engine.block.setHeight(page, 1920);


console.log('✓ Scene created with dimensions 1080x1920');

Apply a Template from URL#

To apply a template from a URL, call engine.scene.applyTemplateFromURL() with the template URL. The template content adjusts automatically to fit the current page dimensions.

// Apply a template from URL - content adjusts to fit current page dimensions
const templateUrl =
  'https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene';


await engine.scene.applyTemplateFromURL(templateUrl);
console.log('✓ Template applied from URL');

Verify Preserved Dimensions#

After applying the template, the page dimensions remain unchanged. You can verify this by checking the width and height of the page.

// Verify that page dimensions are preserved after applying template
const width = engine.block.getWidth(page);
const height = engine.block.getHeight(page);
console.log(`✓ Page dimensions preserved: ${width}x${height}`);

Export with Consistent Dimensions#

Export the result with the same dimensions you configured. This ensures all outputs have the same size regardless of the original template dimensions.

// Export the result with consistent dimensions
const blob = await engine.block.export(page, {
  mimeType: 'image/png',
  targetWidth: 1080,
  targetHeight: 1920
});


const buffer = Buffer.from(await blob.arrayBuffer());
writeFileSync('template-output.png', buffer);
console.log('✓ Exported to template-output.png');

Template Switching#

You can apply multiple templates to the same scene. Each application replaces the content while preserving the page setup. This is useful for batch processing workflows where you generate multiple variations.

// Demonstrate applying a different template while keeping dimensions
const alternativeTemplateUrl =
  'https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_2.scene';


await engine.scene.applyTemplateFromURL(alternativeTemplateUrl);
console.log('✓ Switched to alternative template');


// Verify dimensions remain the same
const newWidth = engine.block.getWidth(page);
const newHeight = engine.block.getHeight(page);
console.log(`✓ Dimensions after switch: ${newWidth}x${newHeight}`);


// Export the alternative template
const blob2 = await engine.block.export(page, {
  mimeType: 'image/png',
  targetWidth: 1080,
  targetHeight: 1920
});


const buffer2 = Buffer.from(await blob2.arrayBuffer());
writeFileSync('template-output-alternative.png', buffer2);
console.log('✓ Exported alternative to template-output-alternative.png');

Apply a Template from String#

For templates stored in databases or received from APIs, use engine.scene.applyTemplateFromString() with a base64-encoded scene string:

// Scene string typically retrieved from storage or API
const templateString = 'UBQ1ewoiZm9ybWF0Ij...';


// Apply template content to current scene
await engine.scene.applyTemplateFromString(templateString);

Troubleshooting#

No Scene Loaded#

applyTemplateFromString() and applyTemplateFromURL() require an existing scene. Create one first with engine.scene.create().

Template URL Not Accessible#

Verify network connectivity and URL validity. In server environments, ensure your infrastructure can access external URLs.

Content Not Scaling as Expected#

Template content scales to fit the current page dimensions. Verify page dimensions are set before applying the template.