Class: VariableAPI | engine - Vanilla JS/TS

Manage text variables within design templates.

Text variables enable dynamic content replacement in design templates. Variables are stored as key-value pairs and can be referenced in text blocks for automated content updates.

// Configure a text block that displays 'Hello, World'
const block = cesdk.engine.block.create('text');
cesdk.engine.block.setText(block, 'Hello, {{name}}!');
cesdk.engine.variable.setString('name', 'World');

Color, number, image and typeface variables hold typed values. A block property bound to one of them with engine.block.setVariableBinding follows every change of the variable.

cesdk.engine.variable.setColor('brand', { r: 1, g: 0, b: 0, a: 1 });
cesdk.engine.block.setVariableBinding(fill, 'fill/color/value', 'brand');

Constructors#

Constructor#

VariableAPI

Variable Management#

Create, update, retrieve, and remove variables from the engine.

findAll()#

Get all text variable names currently stored in the engine.

Returns#

string[]

List of variable names.

Signature#

findAll(): string[]

setString()#

Set a text variable’s value.

Creates a new variable if the key doesn’t exist, or updates an existing one.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`value`	`string`	The text value to assign to the variable.

Returns#

void

Signature#

setString(key: string, value: string): void

getString()#

Get a text variable’s value.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.

Returns#

string

The text value of the variable.

Signature#

getString(key: string): string

remove()#

Remove a variable of any type from the engine.

Bound properties keep their last value and their binding, so direct writes to them still fail with BLOCK.PROPERTY_BOUND. Setting a variable with the same key and type again makes them follow it again.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key to remove.

Returns#

void

Signature#

remove(key: string): void

rename()#

Rename a variable of any type. Experimental: this API may change in a minor release.

The value and the type move to the new key. Every block property bound to the variable follows the new key and keeps its value. For a text variable, every {{key}} token in text blocks is rewritten too.

engine.variable.rename('accent', 'brand/accent');

Parameters#

Parameter	Type	Description
`from`	`string`	The current key of the variable.
`to`	`string`	The new key. It must not be empty, start or end with whitespace, contain `{{` or `}}`, or name another variable.

Returns#

void

Signature#

rename(from: string, to: string): void

setColor()#

Set a color variable’s value. Experimental: this API may change in a minor release.

Creates a new variable if the key doesn’t exist. Every block property bound to the variable takes the new color. If a bound property rejects the value, the call throws its error, but the variable and the other bound properties change anyway.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`value`	`Color`	The color to assign to the variable.

Returns#

void

Signature#

setColor(key: string, value: Color): void

getColor()#

Get a color variable’s value. Experimental: this API may change in a minor release.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.

Returns#

Color

The color value of the variable.

Signature#

getColor(key: string): Color

setNumber()#

Set a number variable’s value. Experimental: this API may change in a minor release.

Creates a new variable if the key doesn’t exist. Every block property bound to the variable takes the new number. If a bound property rejects the value, the call throws its error, but the variable and the other bound properties change anyway.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`value`	`number`	The finite number to assign to the variable.

Returns#

void

Signature#

setNumber(key: string, value: number): void

getNumber()#

Get a number variable’s value. Experimental: this API may change in a minor release.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.

Returns#

number

The number value of the variable.

Signature#

getNumber(key: string): number

setImage()#

Set an image variable’s URI. Experimental: this API may change in a minor release.

Creates a new variable if the key doesn’t exist. Every block property bound to the variable takes the new URI. If a bound property rejects the value, the call throws its error, but the variable and the other bound properties change anyway.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`uri`	`string`	The URI of the image.

Returns#

void

Signature#

setImage(key: string, uri: string): void

getImage()#

Get an image variable’s URI. Experimental: this API may change in a minor release.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.

Returns#

string

The URI of the image.

Signature#

getImage(key: string): string

setTypeface()#

Set a typeface variable’s value. Experimental: this API may change in a minor release.

Creates a new variable if the key doesn’t exist. Every text block whose typeface is bound to the variable takes the new typeface over its whole text. Bold and italic text keeps its formatting where the typeface supports it. If a bound property rejects the value, the call throws its error, but the variable and the other bound properties change anyway.

engine.variable.setTypeface('heading', typeface);
engine.block.setVariableBinding(text, 'text/typeface', 'heading');

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`typeface`	`Typeface`	The typeface. It needs a name and at least one font.

Returns#

void

Signature#

setTypeface(key: string, typeface: Typeface): void

getTypeface()#

Get a typeface variable’s value. Experimental: this API may change in a minor release.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.

Returns#

Typeface

The typeface of the variable.

Signature#

getTypeface(key: string): Typeface

getType()#

Get the type of a variable. Experimental: this API may change in a minor release.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.

Returns#

VariableType

The variable’s type.

Signature#

getType(key: string): VariableType

findAllOfType()#

Get the keys of all variables of one type. Experimental: this API may change in a minor release.

findAll returns only text variables.

Parameters#

Parameter	Type	Description
`type`	`VariableType`	The type of the variables.

Returns#

string[]

List of variable keys.

Signature#

findAllOfType(type: VariableType): string[]