Class Product

A Customer's Canvas product.

Inheritance
ModelComponent
Product
Package: @aurigma/design-editor-iframe
Remarks

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Product class.

Properties

currentSurface

A surface (page) currently opened in the editor.

Declaration
currentSurface: Surface;
Property Value
Type Description
Surface

A surface (page) currently opened in the editor.
Examples
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);
  });

currentSurfaceIndex

Declaration
get currentSurfaceIndex(): number;
Property Value
Type Description
number

surfaces

Product surfaces (pages).

Declaration
surfaces: Surface[];
Property Value
Type Description
Surface[]

Product surfaces (pages).
Examples
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);
  });

Methods

addSurface(surface, position)

Adds the given surface (page) to the product.

Declaration
addSurface(surface: SurfaceTypes | IStateSurface, position?: number): Promise<Product>;
Parameters
Type Name Description
SurfaceTypes | IStateSurface surface

A surface (page) to add.
number position

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
Type Description
Promise<Product>

The product instance where the surface (page) was added.
Examples
  // 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);
      });

addSurfaces(surfaces, position)

Adds a number of surfaces (pages) to the product.

Declaration
addSurfaces(surfaces: SurfaceTypes[] | IStateSurfaces, position?: number): Promise<Product>;
Parameters
Type Name Description
SurfaceTypes[] | IStateSurfaces surfaces

An array of surfaces (pages) to add.
number position

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
Type Description
Promise<Product>

The product instance where the surfaces (pages) were added.
Examples
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));

applyProductTheme(theme, options)

Applies a color theme to the product.

Declaration
applyProductTheme(theme: string | IProductThemeConfig, options?: IApplyProductThemeOptions): Promise<void>;
Parameters
Type Name Description
string | IProductThemeConfig theme

A name of a color theme defined for the current product or through the **clientConfig.json** file.
IApplyProductThemeOptions options

Options for managing the history of user actions.
Returns
Type Description
Promise<void>
Examples
// 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
        });

changeBackground(surfaces, data)

Sets an image or a plain color to the background.

Declaration
changeBackground(surfaces: Surface[], data: ImageMetaData | Color): Promise<ShapeItem[]>;
Parameters
Type Name Description
Surface[] surfaces

An array of surfaces where the background should be changed.
ImageMetaData | Color data

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
Type Description
Promise<ShapeItem[]>

An array of shape items.
Examples
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");
}

getAllItems(options)

Lists all design elements in the product.

Declaration
getAllItems(options?: {
        includeMockup: boolean;
    }): Promise<Item[]>;
Parameters
Type Name Description
{ includeMockup: boolean; } 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.
Returns
Type Description
Promise<Item[]>

An array of elements from all product pages.
Examples
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");

getItemById(id)

Declaration
getItemById(id: string): Promise<CCBaseItem>;
Parameters
Type Name Description
string id
Returns
Type Description
Promise<BaseItem>

getItemByName(name)

Declaration
getItemByName(name: string): Promise<CCBaseItem>;
Parameters
Type Name Description
string name
Returns
Type Description
Promise<BaseItem>

getItemRectangles(ids)

Gets the bounding rectangles for design elements with regard to their rotation.

Declaration
getItemRectangles(ids: string[]): Promise<RotatedRectangleF[]>;
Parameters
Type Name Description
string[] ids

An array of item identifiers.
Returns
Type Description
Promise<RotatedRectangleF[]>

An array of item bounds, in points.
Examples

In the following example, toRectangleF() returns the bounds without taking into account the item rotation, i.e. the vertically or horizontally oriented rectangle, whereas rotatedRect contains the rotation angle and bounds.

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(predicate, args)

Declaration
getItems(predicate: (item: CCBaseItem, args?: object) => boolean, args?: object): Promise<CCBaseItem[]>;
Parameters
Type Name Description
(item: BaseItem, args?: object) => boolean predicate
object args
Returns
Type Description
Promise<BaseItem[]>

getProductModel()

Declaration
getProductModel(): Promise<CCProduct>;
Returns
Type Description
Promise<Product_2>

getTags()

Reads product tags.

Declaration
getTags(): Promise<ITagsDictionary>;
Returns
Type Description
Promise<ITagsDictionary>

The dictionary of product tags.

getVariableItems()

Lists all variable items in the product.

Declaration
getVariableItems(): Promise<IVariable[]>;
Returns
Type Description
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.
Examples
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.");

getViolationData()

Declaration
getViolationData(): Promise<Editor.IViolationWarningData[]>;
Returns
Type Description
Promise<Editor.IViolationWarningData[]>

removeItemById(id)

Declaration
removeItemById(id: string): Promise<void>;
Parameters
Type Name Description
string id
Returns
Type Description
Promise<void>

removeItemByName(name)

Declaration
removeItemByName(name: string): Promise<void>;
Parameters
Type Name Description
string name
Returns
Type Description
Promise<void>

removeItems(predicate, args)

Declaration
removeItems(predicate: (item: CCBaseItem, args?: object) => boolean, args?: object): Promise<string[]>;
Parameters
Type Name Description
(item: BaseItem, args?: object) => boolean predicate
object args
Returns
Type Description
Promise<string[]>

removeSurface(surface)

Removes the given surface (page) from the product.

Declaration
removeSurface(surface: Surface): Promise<Product>;
Parameters
Type Name Description
Surface surface

A surface (page) to remove.
Returns
Type Description
Promise<Product>

The product instance where the surface (page) was removed from.
Examples
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));

setItem(item)

Declaration
setItem(item: CCBaseItem): Promise<unknown>;
Parameters
Type Name Description
CCBaseItem item
Returns
Type Description
Promise<unknown>

setMockups(mockupsData, options)

Sets mockups for several product pages.

Declaration
setMockups(mockupsData: IMockupData[], options?: ISetMockupOptions): Promise<Product>;
Parameters
Type Name Description
IMockupData[] mockupsData

The product surface with mockups and preview mockups.
ISetMockupOptions options

Additional options for managing history and surface size.
Returns
Type Description
Promise<Product>

A new product instance containing the changed surfaces.
Examples
  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));

setProductModel(product)

Declaration
setProductModel(product: CCProduct): Promise<unknown>;
Parameters
Type Name Description
CCProduct product
Returns
Type Description
Promise<unknown>

setSurfaces(surfaces)

Replaces a product.

Declaration
setSurfaces(surfaces: SurfaceTypes[]): Promise<Product>;
Parameters
Type Name Description
SurfaceTypes[] surfaces

An array of the new surfaces.
Returns
Type Description
Promise<Product>

The product instance with the new surfaces.
Examples
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));

setTags(tags)

Specifies tags for the product.

Declaration
setTags(tags: ITagsDictionary): Promise<void>;
Parameters
Type Name Description
ITagsDictionary tags

The tags that you want to specify for the product.
Returns
Type Description
Promise<void>
Examples
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));

swapSurfaces(lhsSurface, rhsSurface)

Swaps two surfaces (pages) in the product.

Declaration
swapSurfaces(lhsSurface: Surface, rhsSurface: Surface): Promise<Product>;
Parameters
Type Name Description
Surface lhsSurface

The first surface (page) to swap.
Surface rhsSurface

The second surface (page) to swap.
Returns
Type Description
Promise<Product>

The product instance where the surfaces (pages) were swapped.
Examples
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));

switchTo(surface)

Opens the given product surface in the designer.

Declaration
switchTo(surface: Surface): Promise<Product>;
Parameters
Type Name Description
Surface surface

A surface (page) to open.
Returns
Type Description
Promise<Product>

The product with the given surface (page) opened.
Examples
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);
  });

updateSurfaces(params)

Replaces surfaces and returns a new product instance with the updated surfaces.

Declaration
updateSurfaces(params: IUpdateSurfaceOptionsByDefinition): Promise<Product>;
Parameters
Type Name Description
IUpdateSurfaceOptionsByDefinition params

Additional parameters for changing surfaces.
Returns
Type Description
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.

Examples

In this example, we take surfaces 1 and 4 from the specified state file and insert them instead of surfaces 0 and 1 in the loaded product.

   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);
Was this page helpful?
Back to top Copyright © 2001–2025 Aurigma, Inc. All rights reserved.