Modify Properties

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to modify block properties through the block API.

Setup#

This example uses the headless CreativeEngine. See the Setup article for a detailed guide. To get started right away, you can also access the block API within a running CE.SDK instance via cesdk.engine.block. Check out the APIs Overview to see that illustrated in more detail.

UUID#

A universally unique identifier (UUID) is assigned to each block upon creation and can be queried. This is stable across save & load and may be used to reference blocks.

JavaScript


getUUID(id: DesignBlockId): string

Get a block's UUID.

id: The block to query.

Reflection#

For every block, you can get a list of all its properties by calling findAllProperties(id: number): string[]. Properties specific to a block are prefixed with the block's type followed by a forward slash. There are also common properties shared between blocks which are prefixed by their respective type. A list of all properties can be found in the Blocks Overview.

JavaScript


findAllProperties(id: DesignBlockId): string[]

Get all available properties of a block.

id: The block whose properties should be queried.
Returns A list of the property names.

JavaScript


getPropertyType(property: string): PropertyType

Get the type of a property given its name.

property: The name of the property whose type should be queried.
Returns The property type.

The property type 'Enum' is a special type. Properties of this type only accept a set of certain strings. To get a list of possible values for an enum property call getEnumValues(enumProperty: string): string[].

JavaScript


getEnumValues<T = string>(enumProperty: string): T[]

Get all the possible values of an enum given an enum property.

enumProperty: The name of the property whose enum values should be queried.
Returns A list of the enum value names as string.

Some properties can only be written to or only be read. To find out what is possible with a property, you can use the isPropertyReadable and isPropertyWritable methods.

JavaScript


isPropertyReadable(property: string): boolean

Check if a property with a given name is readable

property: The name of the property whose type should be queried.
Returns Whether the property is readable or not. Will return false for unknown properties

JavaScript


isPropertyWritable(property: string): boolean

Check if a property with a given name is writable

property: The name of the property whose type should be queried.
Returns Whether the property is writable or not. Will return false for unknown properties

Generic Properties#

There are dedicated setter and getter functions for each property type. You have to provide a block and the property path. Use findAllProperties to get a list of all the available properties a block has.

Please make sure you call the setter and getter function matching the type of the property you want to set or query or else you will get an error. Use `getPropertyType` to figure out the pair of functions you need to use.

JavaScript


findAllProperties(id: DesignBlockId): string[]

Get all available properties of a block.

id: The block whose properties should be queried.
Returns A list of the property names.

JavaScript


setBool(id: DesignBlockId, property: string, value: boolean): void

Set a bool property of the given design block to the given value.

id: The block whose property should be set.
property: The name of the property to set.
value: The value to set.

JavaScript


getBool(id: DesignBlockId, property: string): boolean

Get the value of a bool property of the given design block.

id: The block whose property should be queried.
property: The name of the property to query.
Returns The value of the property.

JavaScript


setInt(id: DesignBlockId, property: string, value: number): void

Set an int property of the given design block to the given value.

id: The block whose property should be set.
property: The name of the property to set.
value: The value to set.

JavaScript


getInt(id: DesignBlockId, property: string): number

Get the value of an int property of the given design block.

id: The block whose property should be queried.
property: The name of the property to query.
Returns The value of the property.

JavaScript


setFloat(id: DesignBlockId, property: string, value: number): void

Set a float property of the given design block to the given value.

id: The block whose property should be set.
property: The name of the property to set.
value: The value to set.

JavaScript


getFloat(id: DesignBlockId, property: string): number

Get the value of a float property of the given design block.

id: The block whose property should be queried.
property: The name of the property to query.
Returns The value of the property.

JavaScript


setDouble(id: DesignBlockId, property: string, value: number): void

Set a double property of the given design block to the given value.

id: The block whose property should be set.
property: The name of the property to set.
value: The value to set.

JavaScript


getDouble(id: DesignBlockId, property: string): number

Get the value of a double property of the given design block.

id: The block whose property should be queried.
property: The name of the property to query.
Returns The value of the property.

JavaScript


setString(id: DesignBlockId, property: string, value: string): void

Set a string property of the given design block to the given value.

id: The block whose property should be set.
property: The name of the property to set.
value: The value to set.

JavaScript


getString(id: DesignBlockId, property: string): string

Get the value of a string property of the given design block.

id: The block whose property should be queried.
property: The name of the property to query.
Returns The value of the property.

JavaScript


setColor(id: DesignBlockId, property: string, value: Color): void

Set a color property of the given design block to the given value.

id: The block whose property should be set.
property: The name of the property to set.
value: The value to set.

JavaScript


getColor(id: DesignBlockId, property: string): Color

Get the value of a color property of the given design block.

id: The block whose property should be queried.
property: The name of the property to query.
Returns The value of the property.

JavaScript


setEnum<T extends string = string>(id: DesignBlockId, property: string, value: T): void

Set an enum property of the given design block to the given value.

id: The block whose property should be set.
property: The name of the property to set.
value: The enum value as string.

JavaScript


getEnum<T extends string = string>(id: DesignBlockId, property: string): T

Get the value of an enum property of the given design block.

id: The block whose property should be queried.
property: The name of the property to query.
Returns The value as string.

TypeScript


type HorizontalTextAlignment = 'Left' | 'Right' | 'Center'

The horizontal text alignment options.

TypeScript


type VerticalTextAlignment = 'Top' | 'Bottom' | 'Center'

The vertical text alignment options.

JavaScript


setGradientColorStops(id: DesignBlockId, property: string, colors: GradientColorStop[]): void

Set a gradient color stops property of the given design block.

id: The block whose property should be set.
property: The name of the property to set.

JavaScript


getGradientColorStops(id: DesignBlockId, property: string): GradientColorStop[]

Get the gradient color stops property of the given design block.

id: The block whose property should be queried.
property: The name of the property to query.
Returns The gradient colors.

JavaScript


setSourceSet(id: DesignBlockId, property: string, sourceSet: Source[]): void

Set the property of the given block. The crop and content fill mode of the associated block will be set to the default values.

id: The block whose property should be set.
property: The name of the property to set.
sourceSet: The block's new source set.

JavaScript


getSourceSet(id: DesignBlockId, property: string): Source[]

Get the source set value of the given property.

id: The block that should be queried.
property: The name of the property to query.
Returns The block's source set.

JavaScript


addImageFileURIToSourceSet(id: DesignBlockId, property: string, uri: string): Promise<void>

Add a source to the sourceSet property of the given block. If there already exists in source set an image with the same width, that existing image will be replaced. If the source set is or gets empty, the crop and content fill mode of the associated block will be set to the default values. Note: This fetches the resource from the given URI to obtain the image dimensions. It is recommended to use setSourceSet if the dimension is known.

id: The block to update.
property: The name of the property to modify.
uri: The source to add to the source set.

JavaScript


addVideoFileURIToSourceSet(id: DesignBlockId, property: string, uri: string): Promise<void>

Add a video file URI to the sourceSet property of the given block. If there already exists in source set an video with the same width, that existing video will be replaced. If the source set is or gets empty, the crop and content fill mode of the associated block will be set to the default values. Note: This fetches the resource from the given URI to obtain the video dimensions. It is recommended to use setSourceSet if the dimension is known.

id: The block to update.
property: The name of the property to modify.
uri: The source to add to the source set.


const uuid = engine.block.getUUID(block);

const propertyNamesStar = engine.block.findAllProperties(starShape); // Array [ "shape/star/innerDiameter", "shape/star/points", "opacity/value", ... ]
const propertyNamesImage = engine.block.findAllProperties(imageFill); // Array [ "fill/image/imageFileURI", "fill/image/previewFileURI", "fill/image/externalReference", ... ]
const propertyNamesText = engine.block.findAllProperties(text); // Array [ "text/text", "text/fontFileUri", "text/externalReference", "text/fontSize", "text/horizontalAlignment", ... ]

const pointsType = engine.block.getPropertyType('shape/star/points'); // "Int"
const alignmentType = engine.block.getPropertyType('text/horizontalAlignment'); // "Enum"
engine.block.getEnumValues('text/horizontalAlignment');
const readable = engine.block.isPropertyReadable('shape/star/points');
const writable = engine.block.isPropertyWritable('shape/star/points');

// Generic Properties
engine.block.setBool(scene, 'scene/aspectRatioLock', false);
engine.block.getBool(scene, 'scene/aspectRatioLock');
const points = engine.block.getInt(starShape, 'shape/star/points');
engine.block.setInt(starShape, 'shape/star/points', points + 2);
engine.block.setFloat(starShape, 'shape/star/innerDiameter', 0.75);
engine.block.getFloat(starShape, 'shape/star/innerDiameter');
const audio = engine.block.create('audio');
engine.block.appendChild(scene, audio);
engine.block.setDouble(audio, 'playback/duration', 1.0);
engine.block.getDouble(audio, 'playback/duration');

engine.block.setString(text, 'text/text', '*o*');
engine.block.setString(
  imageFill,
  'fill/image/imageFileURI',
  'https://img.ly/static/ubq_samples/sample_4.jpg'
);
engine.block.getString(text, 'text/text');
engine.block.getString(imageFill, 'fill/image/imageFileURI');
engine.block.setColor(colorFill, 'fill/color/value', {
  r: 1,
  g: 1,
  b: 1,
  a: 1
}); // White
engine.block.getColor(colorFill, 'fill/color/value');
engine.block.setEnum(text, 'text/horizontalAlignment', 'Center');
engine.block.setEnum(text, 'text/verticalAlignment', 'Center');
engine.block.getEnum(text, 'text/horizontalAlignment');
engine.block.getEnum(text, 'text/verticalAlignment');
engine.block.setGradientColorStops(gradientFill, 'fill/gradient/colors', [
  { color: { r: 1.0, g: 0.8, b: 0.2, a: 1.0 }, stop: 0 },
  { color: { r: 0.3, g: 0.4, b: 0.7, a: 1.0 }, stop: 1 }
]);
engine.block.getGradientColorStops(gradientFill, 'fill/gradient/colors');

const imageFill = engine.block.createFill('image');
engine.block.setSourceSet(imageFill, 'fill/image/sourceSet', [
  {
    uri: 'http://img.ly/my-image.png',
    width: 800,
    height: 600
  }
]);
const sourceSet = engine.block.getSourceSet(imageFill, 'fill/image/sourceSet');
await engine.block.addImageFileURIToSourceSet(imageFill, 'fill/image/sourceSet', 'https://img.ly/static/ubq_samples/sample_1.jpg');

const videoFill = engine.block.createFill('video');
await engine.block.addVideoFileURIToSourceSet(videoFill, 'fill/video/sourceSet', 'https://img.ly/static/example-assets/sourceset/1x.mp4');