Skip to main content

Class: Product

A Customer's Canvas product.

Extends​

Constructors​

Constructor​

new Product(rawProduct, context): Product

Parameters​

rawProduct​
context​

IContext

Returns​

Product

Overrides​

ModelComponent.constructor

Properties​

id​

id: string

A unique identifier.

Inherited from​

ModelComponent.id

name​

name: string

The item name.

Inherited from​

ModelComponent.name

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​

Surface

The first surface (page) to swap.

rhsSurface​

Surface

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​

SurfaceTypes[]

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​

SurfaceTypes | IStateSurface

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​

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​

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​

Promise<ITagsDictionary>

The dictionary of product tags.

setTags()​

setTags(tags): Promise<void>

Specifies tags for the product.

Parameters​

tags​

ITagsDictionary

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​

IMockupData[]

The product surface with mockups and preview mockups.

options?​

ISetMockupOptions

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()​

getAllItems(options?): Promise<Item[]>

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​

Promise<Item[]>

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[]>

Returns​

Promise<IViolationWarningData[]>

Was this page helpful?