Class: Product
A Customer's Canvas product.
Extends
Constructors
Constructor
new Product(
rawProduct,context):Product
Parameters
rawProduct
context
Returns
Product
Overrides
Properties
id
id:
string
A unique identifier.
Inherited from
name
name:
string
The item name.
Inherited from
surfaces
surfaces:
Surface[]
Product surfaces (pages).
Example
editor.getProduct()
.then(function (product) {
// Get the current surface index.
const indexOfCurrentSurface = product.surfaces.lastIndexOf(product.currentSurface);
if (indexOfCurrentSurface < 0)
throw "Surface not found!";
let indexOfNextSurface = indexOfCurrentSurface + 1;
if (indexOfNextSurface > (product.surfaces.length - 1))
indexOfNextSurface = 0;
// Switch to the next surface.
return product.switchTo(product.surfaces[indexOfNextSurface]);
})
.then(function(result) {
console.log("Surface switched");
})
.catch(function (error) {
console.error("Switching the surfaces failed with exception: ", error);
});
currentSurface
currentSurface:
Surface
A surface (page) currently opened in the editor.
Example
editor.getProduct()
.then(function (product) {
// Remove the current surface.
product.removeSurface(product.currentSurface)
.then(function(result) {
console.log("Surface removed");
});
})
// If there was an error thrown while removing the surface.
.catch(function (error) {
console.error("Removing the surface failed with exception: ", error);
});
Accessors
currentSurfaceIndex
Get Signature
get currentSurfaceIndex():
number
Returns
number
Methods
swapSurfaces()
swapSurfaces(
lhsSurface,rhsSurface):Promise<Product>
Swaps two surfaces (pages) in the product.
Parameters
lhsSurface
The first surface (page) to swap.
rhsSurface
The second surface (page) to swap.
Returns
Promise<Product>
The product instance where the surfaces (pages) were swapped.
Example
let product = await editor.getProduct();
// Swap the first and last pages in the product.
product = await product.swapSurfaces(product.surfaces[0], product.surfaces[product.surfaces.length - 1])
// If an error occurred while swapping pages in the product.
.catch(error => console.error("Swapping surfaces failed with exception: ", error));
setSurfaces()
setSurfaces(
surfaces):Promise<Product>
Replaces a product.
Parameters
surfaces
An array of the new surfaces.
Returns
Promise<Product>
The product instance with the new surfaces.
Example
let product = await editor.getProduct();
// Replace the product with two new pages.
product = await product.setSurfaces([
{ width: 300, height: 300 },
{ designFile: "postcard" }
])
// If an error occurred while replacing pages in the product.
.catch(error => console.error("Setting surfaces failed with exception: ", error));
addSurfaces()
addSurfaces(
surfaces,position?):Promise<Product>
Adds a number of surfaces (pages) to the product.
Parameters
surfaces
SurfaceTypes[] | IStateSurfaces
An array of surfaces (pages) to add.
position?
number
A position in the surface array where new surfaces should be added. The index of the first surface is 0. By default, this method adds pages to the end of the surface array.
Returns
Promise<Product>
The product instance where the surfaces (pages) were added.
Example
let product = await editor.getProduct();
// Add an empty page and the "postcard" template to the beginning.
product = await product.addSurfaces(
[{ width: 300, height: 300 }, { designFile: "postcard" }],
0
)
// If an error occurred while adding pages to the product.
.catch(error => console.error("Adding surfaces failed with exception: ", error));
addSurface()
addSurface(
surface,position?):Promise<Product>
Adds the given surface (page) to the product.
Parameters
surface
A surface (page) to add.
position?
number
A position in the surface array where the new surface (page) should be added. The index of the first surface is 0. By default, this method adds pages to the end of the surface array.
Returns
Promise<Product>
The product instance where the surface (page) was added.
Example
// Let us add a back side to the postcard.
editor.getProduct()
// When we get the product.
.then(function(product) {
// If postcard has no back side.
if (product.surfaces.length < 2) {
// Adding the back to the loaded product.
return product.addSurface(
{
// Defining the template file.
printAreas: `[{ designFile: "postcard_side2"}]`
})
// If the back side is added to the postcard.
.then(function(newProduct) {
// Replace the loaded product with the new one.
product = newProduct;
});
}
})
// If there was an error while getting the product or adding a back side to the postcard.
.catch(function (error) {
console.error("Adding surface failed with exception: ", error);
});
removeSurface()
removeSurface(
surface):Promise<Product>
Removes the given surface (page) from the product.
Parameters
surface
A surface (page) to remove.
Returns
Promise<Product>
The product instance where the surface (page) was removed from.
Example
let product = await editor.getProduct();
// Remove the current surface.
product = await product.removeSurface(product.currentSurface)
// If there was an error thrown while removing the surface.
.catch(error => console.error("Removing the surface failed with exception: ", error));
switchTo()
switchTo(
surface):Promise<Product>
Opens the given product surface in the designer.
Parameters
surface
A surface (page) to open.
Returns
Promise<Product>
The product with the given surface (page) opened.
Example
editor.getProduct()
.then(function (product) {
// Get the current surface index.
const indexOfCurrentSurface = product.surfaces.lastIndexOf(product.currentSurface);
if (indexOfCurrentSurface < 0)
throw "Surface not found!";
let indexOfNextSurface = indexOfCurrentSurface + 1;
if (indexOfNextSurface > (product.surfaces.length - 1))
indexOfNextSurface = 0;
// Switch to the next surface.
return product.switchTo(product.surfaces[indexOfNextSurface]);
})
.then(function(result) {
console.log("Surface switched");
})
.catch(function (error) {
console.error("Switching the surfaces failed with exception: ", error);
});
getTags()
getTags():
Promise<ITagsDictionary>
Reads product tags.
Returns
The dictionary of product tags.
setTags()
setTags(
tags):Promise<void>
Specifies tags for the product.
Parameters
tags
The tags that you want to specify for the product.
Returns
Promise<void>
Example
let newTags = {
"product": "postcard",
"design": "flowers",
"colorTheme": "red"
};
let product = await editor.getProduct();
await product.setTags(newTags)
.catch(error => console.error("Setting tags failed with exception: ", error));
setMockups()
setMockups(
mockupsData,options?):Promise<Product>
Sets mockups for several product pages.
Parameters
mockupsData
The product surface with mockups and preview mockups.
options?
Additional options for managing history and surface size.
Returns
Promise<Product>
A new product instance containing the changed surfaces.
Example
let newMockups = [
{
surface: product.surfaces[0],
mockup: null
}, {
surface: product.surfaces[1],
mockup: { up: "mockup1" }
}, {
surface: product.surfaces[2],
mockup: { up: "mockup2" }
}
];
let options = {
addToHistory: false,
resetHistory: true,
updateSurfaceSize: true
};
let product = await editor.getProduct();
product = await product.setMockups(newMockups, options)
.catch(error => console.error("Failed to set up the mockups: ", error));
applyProductTheme()
applyProductTheme(
theme,options?):Promise<void>
Applies a color theme to the product.
Parameters
theme
any
A name of a color theme defined for the current product or through the clientConfig.json file.
options?
IApplyProductThemeOptions = ...
Options for managing the history of user actions.
Returns
Promise<void>
Example
// Define a color theme.
const productTheme = {
"violet": {
"C01": "rgb(102,45,145)",
"C02": "rgb(150,67,214)",
"C03": "rgb(190,107,255)",
"C04": "rgb(32,18,77)"
}
};
// Enable the violet theme.
const editor = await CustomersCanvas.IframeApi.loadEditor(iframe, productDefinition,
{ productThemes: productTheme, defaultProductTheme: "violet" })
// If an error occurred while loading the editor.
.catch(e => console.log(e));
// If the editor has been successfully loaded, change the color theme.
await editor.applyProductTheme({
"C01": "rgb(241,160,175)",
"C02": "rgb(255,200,214)",
"C03": "rgb(255,255,255)",
"C04": "rgb(224,102,102)"
},
// Don't save the theme change in the history.
{
addToHistory: false
});
getAllItems()
Lists all design elements in the product.
Parameters
options?
Additional parameters. You can pass options.includeMockup with the value false to not add mockup items to the list. By default, mockup items will be added to the resulting array.
includeMockup
boolean = true
Returns
An array of elements from all product pages.
Example
let product = await editor.getProduct();
// Get the item list.
const items = await product.getAllItems({includeMockup: false});
console.log("The product contains " + items.length + " design elements");
getProductModel()
getProductModel():
Promise<CCProduct>
Returns
Promise<CCProduct>
setProductModel()
setProductModel(
product):Promise<unknown>
Parameters
product
CCProduct
Returns
Promise<unknown>
getItemRectangles()
getItemRectangles(
ids):Promise<any[]>
Gets the bounding rectangles for design elements with regard to their rotation.
Parameters
ids
string[]
An array of item identifiers.
Returns
Promise<any[]>
An array of item bounds, in points.
Example
const ids = (await editor.getSelectedItems()).map(item => item.id);
if (ids.length > 0) {
var product = await editor.getProduct();
var rectangles = await product.getItemRectangles(ids);
var message = "";
for (let i = 0; i < rectangles.length; i++) {
const rotatedRect = rectangles[i];
const rect = rotatedRect.toRectangleF();
message += "Item with " + ids[i] +
" has: width: " + rect.width.toFixed(2) +
", height: " + rect.height.toFixed(2) +
", location: (" + rect.left.toFixed(2) + ", " + rect.top.toFixed(2) + ")" +
", angle: " + rotatedRect.angle.toFixed(2) + "\n";
}
console.log(message);
}
getItems()
getItems(
predicate,args?):Promise<CCBaseItem[]>
Parameters
predicate
(item, args?) => boolean
args?
object
Returns
Promise<CCBaseItem[]>
setItem()
setItem(
item):Promise<unknown>
Parameters
item
CCBaseItem
Returns
Promise<unknown>
getItemById()
getItemById(
id):Promise<CCBaseItem>
Parameters
id
string
Returns
Promise<CCBaseItem>
getItemByName()
getItemByName(
name):Promise<CCBaseItem>
Parameters
name
string
Returns
Promise<CCBaseItem>
removeItems()
removeItems(
predicate,args?):Promise<string[]>
Parameters
predicate
(item, args?) => boolean
args?
object
Returns
Promise<string[]>
removeItemById()
removeItemById(
id):Promise<void>
Parameters
id
string
Returns
Promise<void>
removeItemByName()
removeItemByName(
name):Promise<void>
Parameters
name
string
Returns
Promise<void>
getVariableItems()
getVariableItems():
Promise<IVariable[]>
Lists all variable items in the product.
Returns
Promise<IVariable[]>
An array of variable items. The isVariable property of these design elements is set to true. Also, this array contains in-string and interpolation placeholders.
Example
let product = await editor.getProduct();
let items = await product.getVariableItems();
if (items.length)
items.forEach(item => console.log(item.name));
else
console.log("This product contains no variable items.");
changeBackground()
changeBackground(
surfaces,data):Promise<ShapeItem[]>
Sets an image or a plain color to the background.
Parameters
surfaces
Surface[]
An array of surfaces where the background should be changed.
data
any
Either an object representing the image metadata or a string representing the color in CCS format (for example: "DeepSkyBlue", "rgb(48,194,255)", "#30C2FF").
Returns
Promise<ShapeItem[]>
An array of shape items.
Example
changeBackground = async () => {
// Get the product loaded into the editor.
let product = await editor.getProduct();
// Get metadata of an image in the public gallery.
const metaData = await editor.configuration.getImageMetadata("public:backgrounds/azure.jpg");
// Apply the image to the background of the first surface.
product.changeBackground([product.surfaces[0]], metaData);
// Apply the color to the background of the second surface.
product.changeBackground([product.surfaces[1]], "#30C2FF");
}
updateSurfaces()
updateSurfaces(
params):Promise<Product>
Replaces surfaces and returns a new product instance with the updated surfaces.
Parameters
params
IUpdateSurfaceOptionsByDefinition
Additional parameters for changing surfaces.
Returns
Promise<Product>
A new product instance containing the changed surface.
Remarks
By default, updateSurfaces moves only texts and image placeholders to new positions and drops other design elements. Note that this method changes the content of placeholders having the same layer names on the current Surface and in the new layout. To maintain the rest elements, set the replaceAll param to true. In this case, the rest of placeholders take content in a random order according to their type. If the old layout had more placeholders than the new layout, then extra placeholders are removed.
If the current and the new surfaces have different sizes, you can specify whether to update the surface size to match the new one by using the updateSurfaceSize param.
Example
let product = await editor.getProduct();
let options = {
replaceAll: true,
definition: "7a6ecf23-1286-4e90-8f18-c7c1c77e3cb0",
surfaces: [0, 1],
newProductSurfaces: [1, 4]
};
await product.updateSurfaces(options);
getViolationData()
getViolationData():
Promise<IViolationWarningData[]>