Utils

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to

Control URI lookups.
Perform color conversions in the editor API.
Look up the MIME type of a resource.
Get information about all transient resources (i.e. resources whose data would be lost if the scene is exported).
Get a resource's data.
Relocate a resource (i.e. update the URL of a resource).

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.

URI Resolver#

The CreativeEngine allows overriding how URI's are resolved at runtime using the following APIs. See the in-depth guide for more details.

JavaScript


setURIResolver(resolver: (URI: string, defaultURIResolver: (URI: string) => string) => string): void

Sets a custom URI resolver. This function can be called more than once. Subsequent calls will overwrite previous calls. To remove a previously set resolver, pass the value null. The given function must return an absolute path with a scheme.

resolver: Custom resolution function. The resolution function should not reference variables outside of its scope. It receives the default URI resolver as its second argument

JavaScript


getAbsoluteURI(relativePath: string): string

Resolves the given path. If a custom resolver has been set with setURIResolver, it invokes it with the given path. Else, it resolves it as relative to the basePath setting. This performs NO validation of whether a file exists at the specified location.

relativePath: A relative path string
Returns The resolved absolute uri or an error if an invalid path was given.

JavaScript


defaultURIResolver(relativePath: string): string

This is the default implementation for the URI resolver. It resolves the given path relative to the basePath setting.

relativePath: The relative path that should be resolved.
Returns The resolved absolute URI.

Color Conversions#

To ease implementing advanced color interfaces, you may rely on the engine to perform color conversions.

JavaScript


convertColorToColorSpace(color: Color, colorSpace: 'sRGB'): RGBAColor

Converts a color to the given color space.

color: The color to convert.
colorSpace: The color space to convert to.
Returns The converted color.

JavaScript


convertColorToColorSpace(color: Color, colorSpace: 'CMYK'): CMYKColor

JavaScript


convertColorToColorSpace(color: Color, colorSpace: ColorSpace): never

Retrieving the mimetype of a resource#

JavaScript


getMimeType(uri: string): Promise<string>

Returns the mimetype of the resources at the given URI. If the resource is not already downloaded, this function will download it.

uri: The URI of the resource.
Returns The mimetype of the resource.
Throws An error if the resource could not be downloaded or the mimetype could not be determined.

Working with resources#

JavaScript


findAllTransientResources(): TransientResource[]

Returns the URLs and sizes of all resources whose data would be lost if the scene was exported. This function is useful for determining which resources need to be relocated (e.g., to a CDN) before exporting a scene since the resources are not included in the exported scene.

Returns The URLs and sizes of transient resources.

JavaScript


getResourceData(uri: string, chunkSize: number, onData: (result: Uint8Array) => boolean): void

Provides the data of a resource at the given URL.

url: The URL of the resource.
chunkSize: The size of the chunks in which the resource data is provided.
onData: The callback function that is called with the resource data or an error if an error occurred. The callback will be called as long as there is data left to provide and the callback returns true.

JavaScript


relocateResource(currentUrl: string, relocatedUrl: string): void

Changes the URL associated with a resource. This function can be used change the URL of a resource that has been relocated (e.g., to a CDN).

currentURL: The current URL of the resource.
relocatedURL: The new URL of the resource.


// Replace all .jpg files with the IMG.LY logo!
engine.editor.setURIResolver((uri) => {
  if (uri.endsWith('.jpg')) {
    return 'https://img.ly/static/ubq_samples/imgly_logo.jpg';
  }
  // Make use of the default URI resolution behavior.
  return engine.editor.defaultURIResolver(uri);
});

// The custom resolver will return a path to the IMG.LY logo because the given path ends with '.jpg'.
// This applies regardless if the given path is relative or absolute.
engine.editor.getAbsoluteURI('/banana.jpg');

// Convert a color
const color = engine.block.getStrokeColor(block);
const cmykColor = engine.editor.convertColorToColorSpace(color, 'CMYK');

// Get the mimetype of a resource
const mimeType = await engine.editor.getMimeType('https://cdn.img.ly/assets/demo/v1/ly.img.image/images/sample_1.jpg');

// Get information about all transient resources.
const transientResources = engine.editor.findAllTransientResources();

// Get a resource's data.
// We retrieve the data of the image fill of the currently selected block, in chunks of 1024 bytes.
engine.editor.getResourceData(block.getString(block.getFill(block.findAllSelected()[0]), 'fill/image/imageFileURI'), 1024, (result) => {
    // ...
    return true;
})

// Relocate a resource.
engine.editor.relocateResource(block.getString(block.getFill(block.findAllSelected()[0]), 'fill/image/imageFileURI'), 'http://your.cdn/image.png');