Class: UtilsAPI | cesdk-js

UtilsAPI provides utility functions for common operations in the Creative Engine SDK.

This API includes utilities for:

Creating and managing loading dialogs
Exporting content (images, PDFs, videos)
Loading and downloading files
Local file uploads

Constructors#

Constructor#

UtilsAPI

Methods#

generateBlockName()#

Generates the automatic, localized fallback name for a design block. When the block does not have an explicit name set, this mirrors the naming shown in the UI panels.

Parameters#

Parameter	Type	Description
`blockId`	`number`	The block ID to generate a fallback name for

Returns#

string

The localized fallback name for the block

Signature#

generateBlockName(blockId: number): string

showLoadingDialog()#

Shows and manages a loading dialog with progress tracking

Parameters#

Parameter	Type	Description
`options?`	{ `title?`: `string`; `message?`: `string`	`string`[]; `cancelLabel?`: `string`; `abortLabel?`: `string`; `abortTitle?`: `string`; `abortMessage?`: `string`
`options.title?`	`string`	-
`options.message?`	`string`	`string`[]
`options.cancelLabel?`	`string`	-
`options.abortLabel?`	`string`	-
`options.abortTitle?`	`string`	-
`options.abortMessage?`	`string`	`string`[]
`options.size?`	`"large"`	`"regular"`
`options.clickOutsideToClose?`	`boolean`	-
`options.progress?`	`DialogProgress`	-
`options.onDone?`	() => `void`	-
`options.onAbort?`	() => `void`	-

Returns#

object

A controller object for managing the dialog

Name	Type
`dialogId`	`string`
`updateProgress()`	(`progress`) => `void`
`showSuccess()`	(`options`) => `void`
`showError()`	(`options`) => `void`
`close()`	() => `void`

Example#

const controller = cesdk.utils.showLoadingDialog({
  title: 'Exporting',
  message: 'Please wait...',
  onAbort: () => console.log('Aborted')
});

// Update progress
controller.updateProgress({ value: 50, max: 100 });

// Show success
controller.showSuccess({
  title: 'Success',
  message: 'Export completed!'
});

Signature#

showLoadingDialog(options?: object): object

export()#

Exports content with a loading dialog and progress tracking. Automatically handles both static exports (images, PDFs) and video exports based on MIME type.

Type Parameters#

Type Parameter
`T` extends

Parameters#

Parameter	Type	Description
`options?`	`T`	Export options. Type inference based on mimeType.

Returns#

Promise<{ blobs: Blob[]; options: T extends VideoExportOptions ? OnExportVideoOptions : OnExportOptions; }>

Export result - either blobs array for static or single blob for video

Example#

// Image export
const imageResult = await cesdk.utils.export({
  mimeType: 'image/png',
  pngCompressionLevel: 7
});

// Video export
const videoResult = await cesdk.utils.export({
  mimeType: 'video/mp4',
  onProgress: (rendered, encoded, total) => console.log(`${rendered}/${total}`)
});

Signature#

export(options?: T): Promise<object>

loadFile()#

Opens a file picker dialog for the user to select a file

Type Parameters#

Type Parameter
`T` extends `"text"`

Parameters#

Parameter	Type	Description
`options`	{ `accept`: `string`; `returnType?`: `T`; }	Options for the file load operation
`options.accept`	`string`	-
`options.returnType?`	`T`	-

Returns#

Promise<T extends "dataURL" ? string : T extends "text" ? string : T extends "blob" ? Blob : T extends "arrayBuffer" ? ArrayBuffer : T extends "objectURL" ? string : File>

The loaded file content in the requested format

Example#

// Load a text file
const text = await cesdk.utils.loadFile({
  accept: '.txt',
  returnType: 'text'
});

// Load an image as blob
const blob = await cesdk.utils.loadFile({
  accept: 'image/*',
  returnType: 'blob'
});

// Load a file as object URL (blob URL)
const objectURL = await cesdk.utils.loadFile({
  accept: '.zip',
  returnType: 'objectURL'
});
// Remember to revoke the object URL when done
URL.revokeObjectURL(objectURL);

Signature#

loadFile(options: object): Promise<T extends "dataURL" ? string : T extends "text" ? string : T extends "blob" ? Blob : T extends "arrayBuffer" ? ArrayBuffer : T extends "objectURL" ? string : File>

downloadFile()#

Downloads a blob or string as a file to the user’s device

Parameters#

Parameter	Type	Description
`file`	`string`	`Blob`
`mimeType?`	`FileMimeType`	The MIME type of the content

Returns#

Promise<void>

Example#

// Download a text file
await cesdk.utils.downloadFile('Hello World', 'text/plain');

// Download a blob
const blob = new Blob(['content'], { type: 'text/plain' });
await cesdk.utils.downloadFile(blob, 'text/plain');

Signature#

downloadFile(file: string | Blob, mimeType?: FileMimeType): Promise<void>

localUpload()#

Performs a local upload of a file (development only)

Note: This is meant for development testing only. In production, you should implement a proper upload handler using the callbacks API.

Parameters#

Parameter	Type	Description
`file`	`File`	The file to upload
`context?`	`UploadCallbackContext`	Optional context information for the upload operation

Returns#

Promise<AssetDefinition>

The asset definition for the uploaded file

Example#

const file = new File(['content'], 'test.txt');
const asset = await cesdk.utils.localUpload(file, {
  context: { source: 'user-upload' }
});

Signature#

localUpload(file: File, context?: UploadCallbackContext): Promise<AssetDefinition>

calculateViewportPadding()#

Calculates the recommended viewport padding based on current viewport size and settings. This utility matches the internal padding used by the SDK for zoom operations. The calculation accounts for safe area insets to ensure content remains visible in UI-safe regions (avoiding notches, rounded corners, system overlays, etc.).

Parameters#

Parameter	Type	Description
`width?`	`number`	Optional viewport width to use instead of current camera width
`height?`	`number`	Optional viewport height to use instead of current camera height

Returns#

object

An object containing paddingX and paddingY values

Name	Type
`paddingX`	`number`
`paddingY`	`number`

Example#

const padding = cesdk.utils.calculateViewportPadding();
console.log(`Padding: ${padding.paddingX}x${padding.paddingY}`);

// Use with custom zoom
await cesdk.engine.scene.zoomToBlock(
  pageId,
  padding.paddingX,
  padding.paddingY,
  padding.paddingX,
  padding.paddingY
);

Signature#

calculateViewportPadding(width?: number, height?: number): object