Manipulating design items through JavaScript

• 4 minutes to read

Starting from version 5, Customer's Canvas provides a set of libraries, which allows you to both create product designs from scratch in the Design Atoms Framework and work directly with the Customer's Canvas object model.

As a front-end API, Design Editor supports the IFrame API representing a JavaScript file IframeApi.js. You can find this file in the ~\Resources\Generated\ folder of Design Editor. To enable the IFrame API on your webpage, include this file as follows:

<!-- To the base URL of your Customers Canvas instance, add Resources/Generated/IframeApi.js -->
<script type="text/javascript" id="CcIframeApiScript" src="https://example.com/cc/Resources/Generated/IframeApi.js">
</script>

Alternatively to the front-end API, you can create your product designs by using the back-end .NET API. To learn how to work with the object model through the .NET API, you can refer to the corresponding section.

Let us describe how you can perform the following basic operations with the object model:

• Getting the product model
• Applying the changes
• Getting and editing single elements
• Adding new elements
• Removing elements

You can also download code samples demonstrating the Design Atoms Framework from GitHub.

Getting the Product Model

To change a product design, you need to load the editor and obtain an instance of the Product class.

document.addEventListener("DOMContentLoaded", async function () {
    let editor = await CustomersCanvas.IframeApi.loadEditor(
        document.getElementById("cc-iframe"),
        productDefinition,
        editorConfig
    );
    let product = await editor.getProduct();
    let productModel = await product.getProductModel();
}

Here, we get an instance of the new Product class from the Design Atoms Framework, which is different from the instance in the IFrame API.

Important

The product model is static. After you have obtained a model from the canvas, it does not link to the canvas. If the user makes further changes, you must obtain the model again. To apply your changes to the model, you need to call setProductModel, as described below.

Applying the Changes

Let us see how you can change your design and apply the changes to the canvas. For example, you can replace the values of all text elements as follows:

let product = await editor.getProduct();
let productModel = await product.getProductModel();

productModel.getAllItems().filter(item => item.type === "PlainTextItem").forEach(textItem => {
    textItem.text = "New text";
});

product.setProductModel(productModel);

The following example illustrates how you can change the product size (for simplicity, design elements remain unchanged).

let product = await editor.getProduct();
let productModel = await product.getProductModel();	
var surface = productModel.surfaces.get(product.currentSurfaceIndex);

surface.width = 400;
surface.height = 400;

product.setProductModel(productModel);

You can also create an object in your code and completely redefine the product model by using this object. In the following example, we create a new 720x360 product, add a text object to it, and replace the product on the canvas with the new product.

let width = 720;
let height = 360;
        
let Model = CustomersCanvas.DesignAtoms.ObjectModel;			
let surface = new Model.Surface(width, height, null, [new Model.PrintArea(new Model.RectangleF(0, 0, width, height))], null, null, true);

const textItem = new Model.PlainTextItem("Hello World", new Model.PointF(width / 2, height / 2), "Roboto-Regular", 40);
textItem.alignment = Model.TextAlignment.Center;
surface.containers.toArray().find(c => c.name === "Main").items.push(textItem);

let newProductModel = new Model.Product([surface]);						

let product = await editor.getProduct();
product.setProductModel(newProductModel);

Getting and Editing Single Elements

In some cases, you don't need to get a product model. If you know that the product contains an element named Logo, you can get it as follows:

let item = await product.getItemByName("Logo");

When you need to get elements that fit a certain criterion, you pass a predicate. It is applied to each design element, and if true is returned, this element is added to the result. So, the following example returns all text elements with a name beginning with Agent.

let items = await product.getItems((item, args) => item.name.startsWith(args.name), { name: "Agent" });

Important

Notice how we pass the argument inside the predicate (in this case, the object containing the name property). You should keep in mind that the predicate is executed inside an IFRAME element, therefore, the variables from the external context are not accessible inside. If you need to use external data, transfer them as an object and refer to the args variable.

To apply changes to a single design element in a product, use the following call:

await product.setItem(item);

Adding New Elements

To add new elements, first create them by using the Design Atoms Framework. You can find all the constructors of design elements in the CustomersCanvas.DesignAtoms.ObjectModel namespace. After you have created an object, you can insert it into your product through the insertItem method. The following example illustrates how you can create a placeholder as large as the product and add this placeholder to the first product page.

var Model = CustomersCanvas.DesignAtoms.ObjectModel;
var currentSurface = product.currentSurface;
var placeholder = new Model.PlaceholderItem(new Model.RectangleF(0, 0, currentSurface.width, currentSurface.height));
currentSurface.insertItem(placeholder);

Removing Elements

The Design Atoms Framework allows you to remove design elements by names and predicates. In the following example, we remove the Logo object and all image items.

await product.removeItems((item, args) => item.name === args.name || item.type === "ImageItem", { name: "Logo" });