Search
Loading...
Skip to content

Placeholders

Placeholders turn design blocks into drop-zones that can be programmatically populated with content while maintaining layout and styling control.

10 mins
estimated time
Download
StackBlitz
GitHub

Placeholders enable content replacement while preserving design constraints. They support both graphic blocks (images/videos) and text blocks, with different configuration approaches for each type.

This guide covers placeholder fundamentals, checking support, enabling behavior, and configuring placeholders for graphic and text blocks programmatically.

Placeholder Fundamentals#

Placeholders convert design blocks into interactive drop-zones where content can be programmatically replaced while maintaining layout and styling control.

Block-Level vs Fill-Level Behavior#

The key distinction in placeholder implementation depends on block type:

For graphic blocks (images/videos): Placeholder behavior is enabled on the fill, not the block itself. This pattern reflects how graphic blocks contain fills that can be replaced.

For text blocks: Placeholder behavior is enabled directly on the block.

We can check support with supportsPlaceholderBehavior() for both blocks and fills.

Checking Placeholder Support#

Before enabling placeholder features, check if a block supports them:

// Step 4: Check if block/fill supports placeholder features
const fill1 = engine.block.getFill(block1);
const supportsBehavior = engine.block.supportsPlaceholderBehavior(fill1);

The supportsPlaceholderBehavior() method indicates whether a block or fill can become a drop-zone. For graphic blocks, we check the fill rather than the block itself.

Enabling Placeholder Behavior#

To convert a block into a placeholder drop-zone, enable placeholder behavior. The approach differs based on block type.

For Graphic Blocks (Images/Videos)#

For graphic blocks, placeholder behavior must be enabled on the fill, not the block itself:

// Enable placeholder behavior on the fill (for graphic blocks)
if (supportsBehavior) {
  engine.block.setPlaceholderBehaviorEnabled(fill1, true);
}

This pattern is critical: setPlaceholderBehaviorEnabled() is called on the fill obtained from block.getFill(). This reflects the underlying architecture where graphic blocks contain replaceable fills.

For Text Blocks#

For text blocks, placeholder behavior is enabled directly on the block. Text blocks don’t use fills in the same way as graphics, so placeholder behavior is configured on the block itself using the same methods (supportsPlaceholderBehavior() and setPlaceholderBehaviorEnabled()) but applied to the block rather than a fill.

We can verify placeholder behavior state with isPlaceholderBehaviorEnabled() on the appropriate target (fill for graphics, block for text).

Enabling Adopter Mode Interaction#

Placeholder behavior alone isn’t enough - blocks must also be enabled for interaction in Adopter mode:

// Step 3: Enable placeholder behavior ("Act as a placeholder")
// This makes the block interactive in Adopter mode
engine.block.setPlaceholderEnabled(block1, true);

The setPlaceholderEnabled() method controls whether the placeholder is interactive for programmatic content replacement. CE.SDK distinguishes Creator (full access) and Adopter (replace-only) roles, and this setting enables the Adopter mode functionality.

Automatic Management#

In practice, setPlaceholderEnabled() is typically managed automatically by the editor: when you enable relevant scopes (like fill/change for graphics or text/edit for text), the placeholder interaction is automatically enabled. When all scopes are disabled, placeholder interaction is automatically disabled.

Scope Requirements and Dependencies#

Placeholders depend on specific scopes being enabled to function correctly. For graphic blocks (images/videos), the fill/change scope must be enabled before placeholder behavior will work. When you disable fill/change, placeholder behavior and interaction are automatically disabled to maintain consistency.

For text blocks, the text/edit scope must be enabled before placeholder behavior can function.

Optional related scopes that enhance placeholder functionality:

  • fill/changeType - Allows changing between image, video, and solid color fills
  • layer/crop - Enables cropping replacement images
  • text/character - Allows font and character formatting for text placeholders

Working with Multiple Placeholders#

When creating templates with multiple placeholders, apply settings systematically:

// Batch operation: Apply settings to multiple blocks
const graphicBlocks = [block1, block2];
graphicBlocks.forEach((block) => {
  // Enable placeholder for each block
  engine.block.setPlaceholderEnabled(block, true);


  const fill = engine.block.getFill(block);
  if (engine.block.supportsPlaceholderBehavior(fill)) {
    engine.block.setPlaceholderBehaviorEnabled(fill, true);
  }
});

This pattern works well for collage templates, product showcases, or any layout requiring multiple content slots.

Exporting Templates#

After configuring placeholders, we export the template for later use:

// Export the template as a scene file for later use
const sceneBlob = await engine.scene.saveToArchive();
const sceneBuffer = Buffer.from(await sceneBlob.arrayBuffer());
writeFileSync(`${outputDir}/placeholders-template.scene`, sceneBuffer);


// Also export a visual preview
const blob = await engine.block.export(page, { mimeType: 'image/png' });
const buffer = Buffer.from(await blob.arrayBuffer());
writeFileSync(`${outputDir}/placeholders-result.png`, buffer);

We save both the template as a scene file and a visual preview as PNG. The scene file preserves all placeholder settings for later use.

Cleanup#

We must dispose the engine to free system resources when processing is complete:

// Always dispose the engine to free resources
engine.dispose();

Always use a try-finally block to ensure the engine is disposed even if errors occur during processing.

API Reference#

MethodDescription
CreativeEngine.init()Initializes the headless engine for programmatic creation
engine.scene.create()Creates a new scene programmatically
engine.block.supportsPlaceholderBehavior()Checks whether the block or fill supports placeholder behavior
engine.block.setPlaceholderBehaviorEnabled()Enables or disables placeholder behavior for a block or fill
engine.block.isPlaceholderBehaviorEnabled()Queries whether placeholder behavior is enabled
engine.block.setPlaceholderEnabled()Enables or disables placeholder interaction in Adopter mode
engine.block.isPlaceholderEnabled()Queries whether placeholder interaction is enabled
engine.block.setScopeEnabled()Enables or disables editing scopes required for placeholder functionality
engine.block.getFill()Gets the fill from a graphic block
engine.block.addImage()Creates and adds an image block to the scene
engine.block.findByType()Finds all blocks of a specific type in the scene
engine.block.export()Exports a block to an image format
engine.scene.saveToArchive()Saves the scene to a .scene archive file
engine.dispose()Disposes the engine and frees resources

Next Steps#

  • Lock the Template - Restrict editing access to specific elements or properties to enforce design rules
  • Text Variables - Define dynamic text elements that can be populated with custom values