Canvas

---

• Embed Placid SDK from CDN

Initializing the Placid Canvas

The Placid Canvas allows you to embed a interactive Placid Template directly into your application. This guide walks you through the steps:

Step 1: Embed the Placid SDK

To get started, you'll need to embed the Placid SDK in your HTML. This can be done by including the following script tag, sourced from Placid's CDN:

<script src="https://sdk.placid.app/editor-sdk@latest/sdk.js"></script>

Step 2: Set Up the Canvas Container

Create a container in your HTML where the canvas will be rendered. For example:

<div id="canvas"></div>

Step 3: Initialize the Canvas

Now, you can initialize the Placid Canvas within the specified container. Use the following JavaScript to create an instance of the canvas:

const canvasInstance = EditorSDK.canvas.create(document.getElementById("canvas"), {
    access_token: "{ YOUR_JWT_TOKEN }",     // Replace with your JWT token
    template_uuid: "{ YOUR_TEMPLATE_UUID }", // Replace with your template UUID
});

{info} Make sure to replace { YOUR_JWT_TOKEN } with your actual JWT token and { YOUR_TEMPLATE_UUID } with the UUID of the template you wish to display.

Canvas Options

Canvas Mode

Set mode to control the interaction behavior of the canvas. By default (no mode), the canvas is an immutable preview.

const canvasInstance = EditorSDK.canvas.create(document.getElementById("canvas"), {
    access_token: "{ YOUR_JWT_TOKEN }",
    template_uuid: "{ YOUR_TEMPLATE_UUID }",
    mode: "select",
});

// Listen for layer clicks
canvasInstance.on('layer:click', (event) => {
    console.log('User clicked:', event.layerName, event.layerType);
});

// Programmatically select a layer
await canvasInstance.selectLayer("title");

// Clear selection
await canvasInstance.deselectAll();

When mode: "select" is set:

• Layers show a pointer cursor on hover
• Hovering a layer highlights it with a border
• Clicking a layer shows a selection border (no resize/rotate handles)
• Layers cannot be dragged or resized — selection only

Canvas Methods

Here's how you can utilize the methods of the canvas:

fillLayers

Fill the template with values based on the REST API notation.

const canvasInstance = /* Your canvas instance */;

canvasInstance.fillLayers({
    "layerText": {
        "text": "This is a text"
    },
    "layerImage": {
        "image": "https://urltoanimage.com/image.jpg"
    }
});

getLayers

Get a list of dynamic layers in the template. Useful for building dynamic UIs based on the template structure.

Returns: Promise<Array<{ name: string, type: string }>>

const canvasInstance = /* Your canvas instance */;

// Works immediately - waits for canvas to be ready internally
const layers = await canvasInstance.getLayers();
// [{ name: "title", type: "text" }, { name: "photo", type: "picture" }]

uploadMedia

Upload a file to temporary storage and get a URL for use with fillLayers().

Parameters:

• file - A File object to upload
• options (optional) - { onProgress: (percent) => void } - Progress callback

Returns: Promise<{ url: string }>

const canvasInstance = /* Your canvas instance */;

const fileInput = document.getElementById('file-input');
const file = fileInput.files[0];

// Upload with progress tracking
const result = await canvasInstance.uploadMedia(file, {
    onProgress: (percent) => console.log(`Uploading: ${percent}%`)
});

// Use the uploaded image in a layer
canvasInstance.fillLayers({
    "photo": {
        "image": result.url
    }
});

resetLayerValues

Reset all layer values back to their original template state, undoing any changes made by fillLayers(). The canvas re-renders in place without any DOM manipulation.

const canvasInstance = /* Your canvas instance */;

// Fill some values
canvasInstance.fillLayers({ "title": { "text": "Test" } });

// Reset to original template state
canvasInstance.resetLayerValues();

selectLayer

Programmatically select a layer by name. Only works when mode: "select" is set.

Parameters:

• layerName - The name of the layer to select

Returns: Promise<boolean> - true if the layer was found and selected, false otherwise

const canvasInstance = /* Your canvas instance */;

const found = await canvasInstance.selectLayer("title");
// true — layer is now selected on the canvas

const notFound = await canvasInstance.selectLayer("nonexistent");
// false — no error, selection unchanged

deselectAll

Clear the current layer selection. Only relevant when mode: "select" is set. Fires a layer:select event with null values.

const canvasInstance = /* Your canvas instance */;

await canvasInstance.deselectAll();

highlightLayer

Programmatically highlight one or more layers on the canvas. Highlighted layers get a visual border; non-highlighted layers dim to 50% opacity. Each call replaces the current highlights. Works in any mode (including immutable preview).

Parameters:

• layerName - A layer name (string) or array of layer names

Returns: Promise<number> - count of layers found and highlighted

const canvasInstance = /* Your canvas instance */;

// Single layer
await canvasInstance.highlightLayer("title");

// Multiple layers
await canvasInstance.highlightLayer(["title", "logo", "subtitle"]);

// Replaces previous highlights — only "logo" highlighted after this
await canvasInstance.highlightLayer("logo");

unhighlightAll

Clear all programmatic highlights.

const canvasInstance = /* Your canvas instance */;

await canvasInstance.unhighlightAll();

Available methods

Canvas Events

The SDK offers a range of events to listen to

const canvasInstance = /* Your canvas instance */;

canvasInstance.on('canvas:loaded', (canvasInstance) => {
    console.log('Canvas has loaded the current changes');
});

// - changing canvas content
canvasInstance.fillLayers(/**/);

Layer Interaction Events

When mode: "select" is set, additional events are available for layer interactions:

const canvasInstance = EditorSDK.canvas.create(element, {
    access_token: "{ YOUR_JWT_TOKEN }",
    template_uuid: "{ YOUR_TEMPLATE_UUID }",
    mode: "select",
});

canvasInstance.on('layer:click', (event) => {
    console.log('Clicked:', event.layerName, event.layerType);
});

canvasInstance.on('layer:select', (event) => {
    // Fires on click AND on programmatic selectLayer() / deselectAll()
    console.log('Selected:', event.layerName, event.layerType);
});

canvasInstance.on('layer:hover', (event) => {
    console.log('Hovering:', event.layerName, event.layerType);
});

canvasInstance.on('layer:hoverend', (event) => {
    console.log('Hover ended:', event.layerName, event.layerType);
});

The event payload contains:

• layerName — the layer name (or null when deselecting via deselectAll())
• layerType — the layer type: text, picture, shape, browserframe, barcode, rating, subtitle (or null when deselecting)

Available events