Class: VariableAPI | engine - React

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');

The scene saves its variables, and undo reverts their changes. A variable set while no scene exists waits for the next scene: that scene takes it when it is created or loaded, and its value replaces the loaded one.

A value set holds alternative values for some variables, such as worst-case texts or a client’s copy. The active set wins over the default values. A call without a target uses the layer that the scene shows, so getString returns what setString wrote.

const longNames = cesdk.engine.variable.createValueSet('Long names');
cesdk.engine.variable.setString('name', 'Maximiliane', { target: { valueSet: longNames } });
cesdk.engine.variable.setActiveValueSet(longNames);
cesdk.engine.variable.getString('name'); // 'Maximiliane'
cesdk.engine.variable.getString('name', { target: 'Default' }); // 'World'

Constructors#

Constructor#

VariableAPI

Variable Management#

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

findAll()#

Get all text variable names of the scene, or of the variables that wait for a scene.

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. The scene saves its variables, and undo reverts their changes. A variable set while no scene exists waits for the next scene. That scene takes it when it is created or loaded, as this setter without a target writes it. A value of another type than the loaded variable is dropped.

A new key must not be empty, start or end with whitespace, contain {{ or }}, or be reserved: scene_root and keys that start with ubq..

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`value`	`string`	The text value to assign to the variable.
`options?`	`VariableOptions`	The layer to write. By default the active value set when it holds the key, else the default value.

Returns#

void

Signature#

setString(key: string, value: string, options?: VariableOptions): void

getString()#

Get a text variable’s value.

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`options?`	`VariableOptions`	The layer to read. By default the value that the scene shows.

Returns#

string

The text value of the variable.

Signature#

getString(key: string, options?: VariableOptions): 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.
`options?`	`VariableOptions`	The layer to remove from. By default, and with the target `'Default'`, the variable goes with its value in every value set. A value set target removes only the value of that set.

Returns#

void

Signature#

remove(key: string, options?: VariableOptions): void

createValueSet()#

Create an empty value set in the scene. Experimental: this API may change in a minor release.

A value set holds alternative values for some scene variables; write them with the target { valueSet: id }. The scene saves its sets, and undo reverts their changes.

Parameters#

Parameter	Type	Description
`name`	`string`	The name of the set. It must be unique among the sets of the scene, must not be empty, and must not start or end with whitespace.

Returns#

string

The id of the new set. The scene saves it, so it stays the same across saves and loads.

Signature#

createValueSet(name: string): string

destroyValueSet()#

Destroy a value set and its values. Experimental: this API may change in a minor release.

When the set is active, no set is active afterwards, and text and bound properties show the default values again.

Parameters#

Parameter	Type	Description
`set`	`string`	The id of the set.

Returns#

void

Signature#

destroyValueSet(set: string): void

setValueSetName()#

Rename a value set. Experimental: this API may change in a minor release.

The id stays, and an active set stays active.

Parameters#

Parameter	Type	Description
`set`	`string`	The id of the set.
`name`	`string`	The new name, valid as for `createValueSet`.

Returns#

void

Signature#

setValueSetName(set: string, name: string): void

getValueSetName()#

Get the name of a value set. Experimental: this API may change in a minor release.

Parameters#

Parameter	Type	Description
`set`	`string`	The id of the set.

Returns#

string

The name of the set.

Signature#

getValueSetName(set: string): string

findAllValueSets()#

Get the value sets of the scene. Experimental: this API may change in a minor release.

Returns#

string[]

The ids of the sets in creation order, empty when no scene exists.

Signature#

findAllValueSets(): string[]

findValueSetByName()#

Find a value set by its name. Experimental: this API may change in a minor release.

const german = engine.variable.findValueSetByName('Deutsch');

Parameters#

Parameter	Type	Description
`name`	`string`	The name of the set.

Returns#

string

The id, or null when no set of the scene has this name or no scene exists.

Signature#

findValueSetByName(name: string): string

setActiveValueSet()#

Activate a value set, or no set. Experimental: this API may change in a minor release.

The values of the active set win over the default values in text, bound properties and getters. Exports show the active set, as the canvas does. A scene has one active set and saves it. Undo reverts the change.

Parameters#

Parameter	Type	Description
`set`	`string`	The id of the set, or null to show the default values.

Returns#

void

Signature#

setActiveValueSet(set: string): void

getActiveValueSet()#

Get the active value set. Experimental: this API may change in a minor release.

Returns#

string

The id of the active set, or null when no set is active or no scene exists.

Signature#

getActiveValueSet(): string

rename()#

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

The value, the type and the values in every value set 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 and page titles is rewritten too. A key inside a longer expression or a statement, such as {% if key %}, is not renamed.

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 `}}`, name another variable, or be reserved: `scene_root` and keys that start with `ubq.`.

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 color that the scene shows. If a bound property rejects the value, the call throws its error, but the variable and the other bound properties change anyway.

A new key must not be empty, start or end with whitespace, contain {{ or }}, or be reserved: scene_root and keys that start with ubq..

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`value`	`Color`	The color to assign to the variable.
`options?`	`VariableOptions`	The layer to write. By default the active value set when it holds the key, else the default value.

Returns#

void

Signature#

setColor(key: string, value: Color, options?: VariableOptions): 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.
`options?`	`VariableOptions`	The layer to read. By default the value that the scene shows.

Returns#

Color

The color value of the variable.

Signature#

getColor(key: string, options?: VariableOptions): 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 number that the scene shows. If a bound property rejects the value, the call throws its error, but the variable and the other bound properties change anyway.

A new key must not be empty, start or end with whitespace, contain {{ or }}, or be reserved: scene_root and keys that start with ubq..

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`value`	`number`	The finite number to assign to the variable.
`options?`	`VariableOptions`	The layer to write. By default the active value set when it holds the key, else the default value.

Returns#

void

Signature#

setNumber(key: string, value: number, options?: VariableOptions): 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.
`options?`	`VariableOptions`	The layer to read. By default the value that the scene shows.

Returns#

number

The number value of the variable.

Signature#

getNumber(key: string, options?: VariableOptions): 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 URI that the scene shows. If a bound property rejects the value, the call throws its error, but the variable and the other bound properties change anyway.

A new key must not be empty, start or end with whitespace, contain {{ or }}, or be reserved: scene_root and keys that start with ubq..

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`uri`	`string`	The URI of the image.
`options?`	`VariableOptions`	The layer to write. By default the active value set when it holds the key, else the default value.

Returns#

void

Signature#

setImage(key: string, uri: string, options?: VariableOptions): 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.
`options?`	`VariableOptions`	The layer to read. By default the value that the scene shows.

Returns#

string

The URI of the image.

Signature#

getImage(key: string, options?: VariableOptions): 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 typeface that the scene shows, 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');

A new key must not be empty, start or end with whitespace, contain {{ or }}, or be reserved: scene_root and keys that start with ubq..

Parameters#

Parameter	Type	Description
`key`	`string`	The variable’s key.
`typeface`	`Typeface`	The typeface. It needs a name and at least one font.
`options?`	`VariableOptions`	The layer to write. By default the active value set when it holds the key, else the default value.

Returns#

void

Signature#

setTypeface(key: string, typeface: Typeface, options?: VariableOptions): 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.
`options?`	`VariableOptions`	The layer to read. By default the value that the scene shows.

Returns#

Typeface

The typeface of the variable.

Signature#

getTypeface(key: string, options?: VariableOptions): 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.
`options?`	`VariableOptions`	The layer to read. By default the value that the scene shows.

Returns#

VariableType

The variable’s type.

Signature#

getType(key: string, options?: VariableOptions): VariableType

findAllOfType()#

Get the keys of all variables of one type, of the scene or of the variables that wait for a scene. 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[]