Templating

A template is a regular CE.SDK scene that contains variable tokens in text and placeholder blocks for media. When you load a template, you can populate the variables with data and swap placeholder content—producing personalized designs without modifying the underlying layout.

import Foundation
import IMGLYEngine

@MainActor
func templating(engine: Engine) async throws {
  let templateURL = URL(
    string: "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene",
  )!
  try await engine.scene.load(from: templateURL)

  let variableNames = engine.variable.findAll()
  print("Template variables:", variableNames)

  try engine.variable.set(key: "Name", value: "Jane")
  try engine.variable.set(key: "Greeting", value: "Wish you were here!")

  let placeholders = engine.block.findAllPlaceholders()
  print("Template placeholders:", placeholders.count)
}

This guide explains the core concepts. For implementation details, see the guides linked in each section.

What Makes a Template#

Any CE.SDK scene can become a template by adding dynamic elements:

Templates separate design (created once by designers) from content (populated at runtime with data). This enables workflows like batch generation, form-based customization, and user personalization.

Loading Templates#

Load a template from a URL using engine.scene.load(from:). This loads the template’s structure into the engine, including any pages, blocks, variables, and placeholders.

let templateURL = URL(
  string: "https://cdn.img.ly/assets/demo/v1/ly.img.template/templates/cesdk_postcard_1.scene",
)!
try await engine.scene.load(from: templateURL)

Templates are standard CE.SDK scene files. You can load them from your own servers, CDNs, or cloud storage.

Variables#

Variables enable dynamic text without modifying the design structure. Text blocks contain {{variableName}} tokens that CE.SDK resolves at render time.

Discovering Variables#

Use engine.variable.findAll() to discover what variables a template expects:

let variableNames = engine.variable.findAll()
print("Template variables:", variableNames)

This returns an array of variable names defined in the template.

Setting Variable Values#

Populate variables with engine.variable.set(key:value:):

try engine.variable.set(key: "Name", value: "Jane")
try engine.variable.set(key: "Greeting", value: "Wish you were here!")

How variables work:

• Reference them in text blocks: Welcome, {{name}}!
• CE.SDK automatically updates all text blocks using that variable
• Tokens are case-sensitive; unmatched tokens render as literal text
• Variables are scene-scoped and persist when you save the template

Placeholders#

Placeholders mark blocks as content slots that users or automation can replace. When you enable placeholder behavior on an image block, it becomes a designated swap target.

Discovering Placeholders#

Use engine.block.findAllPlaceholders() to discover all placeholder blocks in a loaded template:

let placeholders = engine.block.findAllPlaceholders()
print("Template placeholders:", placeholders.count)

How placeholders work:

• Enable with engine.block.setPlaceholderEnabled(_:enabled:)
• Placeholder blocks are marked for content replacement
• You can programmatically replace placeholder content with new images or media

Template Workflows#

Templates support several common workflows:

Batch Generation#

Load a template programmatically, iterate through data records, set variables for each record, and export personalized designs. This powers use cases like certificates, badges, and personalized marketing.

Form-Based Customization#

Load a template, present a form for variable values, and let users customize text while the design stays consistent. The editor UI handles placeholder replacement through drag-and-drop.

Design Systems#

Create template libraries where designers maintain approved layouts and automation populates them with data at scale.

Creating Templates#

Build templates by adding variable tokens to text blocks and configuring placeholder behavior on media blocks. Save with engine.scene.saveToString() or engine.scene.saveToArchive().

Importing Templates#

CE.SDK provides two approaches for working with templates:

Load a template with engine.scene.load(from:) to replace the current scene entirely, including page dimensions.

Apply a template with engine.scene.applyTemplate(from:) to merge template content into an existing scene while preserving current page dimensions.