Migrating Your Application to 5.0

In the Upgrading Customer's Canvas topic you can learn how to upgrade Customer's Canvas from version 4 to version 5. This upgrade may require to modify your application, since version 5 of the Customer's Canvas SDK has introduced significant changes to the object model. For the complete list of deprecated and removed features, you can refer to the Breaking Changes in 5.0. This topic describes how to update an application written for version 4 to version 5.

Removing the Eval Function

In Customer's Canvas 4, you could access the Design Editor and the object model through the spEditor object in the eval function. Although you can still use this way, which is not recommended, the code executed in this function is likely to stop working because of changes in the IFrame API. In the current implementation, you have full access to the object model right through the IFrame API.

Let's see in what use cases you could use eval and how you can replace this function now.

Getting the User ID

Since the userId property has been removed from the object model in version 5, the following call returns undefined.

let editor = await CustomersCanvas.IframeApi.loadEditor(iframe, product, config);
console.log(await editor.eval("spEditor.model.product.userId"));

Instead, you can get the user ID from the runtime configuration as follows:

let editor = await CustomersCanvas.IframeApi.loadEditor(iframe, product, config);
console.log(await editor.configuration.getUserId());

Getting the Product Model

Instead of using the spEditor.model:

let productModel = await editor.eval(() => {
    return spEditor.model.product;
});

You can now obtain a product model as follows:

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

Note that despite the previous way, the model obtained through getProductModel represents only a snapshop of the product loaded into the editor. If you change the model, you need to apply these changes to the product by using the setProductModel method.

product.setProductModel(newProductModel);

Working with Design Elements

Instead of using the spEditor.productHandler object:

let item = spEditor.productHandler.getAllItems().find(x => x.name === "Logo");

For example, you can find an element by its name as follows:

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

Changing the setMockup Calls

In Customer's Canvas 5, you can set a mockup to a surface only through the IMockupTemplate interface. You can use the setMockup method as follows:

let newProduct = await product.currentSurface.setMockup(
    {
        up: "stamp",
        down: "envelope"
    },
    previewMockups: [{ down: "envelope" }]
);

Changing Endpoints of the StateFiles Controller

If your application uses the Web API for manipulating state files through the deprecated endpoint:

~/api/users/{userId}/{stateId}

Then you must replace it with the new endpoint:

~/api/users/{userId}/states/{stateId}

See Also

Manual