Skip to main content

Class: Editor

Represents the Design Editor.

Constructors​

Constructor​

new Editor(iframe, postMessageClient, editorUrl, config?): Editor

Parameters​

iframe​

HTMLIFrameElement

postMessageClient​

Client

editorUrl​

string

config?​

IConfiguration

Returns​

Editor

Properties​

commandManager​

commandManager: CommandManager

Performs operations on design elements, surfaces, print areas, and the entire product.

Accessors​

version​

Get Signature​

get static version(): string

Returns​

string

configuration​

Get Signature​

get configuration(): RuntimeConfiguration

Returns​

RuntimeConfiguration

Methods​

getProofImages()​

getProofImages(options?, data?): Promise<IProofResult>

Renders proof images (72 DPI).

Parameters​

options?​

IGetProofImagesOptions

Parameters of proof images. Note, when defining the width and height, the resulting image will be proportionally resized to fit the defined rectangle. For example, if the maximum width and height are both set to 640 pixels, then a 1280 x 960 px image will be resized to 640 x 480 px. When using mockups, specify the size of proof images more than or equal to the preview mockup size to avoid loss of the image quality.

data?​

IVdpData

Parameters of variable data printing. You can pass either dataSet or itemsData into this method.

Returns​

Promise<IProofResult>

Returns an array of temporary links to proof images.

Example​

// Getting links to proof images.
const renderingResults = await editor
  .getProofImages({
    maxHeight: 720,
    maxWidth: 720,
    pregeneratePreviewImages: true,
  })
  // If an error occurred while getting links to proof images.
  .catch((error) =>
    console.error("Getting proof images failed with exception: ", error),
  );

// If the links to proof images were generated successfully, get the links from the promise properties.
proofImageUrls = renderingResults.proofImageUrls;

finishProductDesign()​

finishProductDesign(options?, data?): Promise<IFinishDesignResult>

Saves the current product state and returns links to the hi-res output.

Parameters​

options?​

IFinishProductDesignOptions

Parameters of the hi-res and preview images.

data?​

IVdpData

Parameters of variable data printing. You can pass either dataSet or itemsData into this method.

Returns​

Promise<IFinishDesignResult>

Returns a promise with the resulting product details: the bounding rectangle, links to the hi-res output, permanent links to proof images, a return-to-edit URL, user changes, userId, and stateId.

Example​

// Completing product customization.
const productDetails = await editor
  .finishProductDesign()
  // If an error occurred while completing product customization.
  .catch((error) =>
    console.error(
      "Completing product customization failed with exception: ",
      error,
    ),
  );

// If product customization is completed successfully, get the promise properties.
stateId = productDetails.stateId;
userId = productDetails.userId;
userChanges = productDetails.userChanges;
console.log("Text user changes: ", userChanges.texts);

parseStringColor()​

parseStringColor(colorString): Promise<IColor>

Parameters​

colorString​

string

Returns​

Promise<IColor>

saveProduct()​

saveProduct(stateId?, data?, options?): Promise<ISaveProductResult>

Saves a product current state.

Parameters​

stateId?​

string

Specifies a state file name without an extension, up to 36 symbols length. If such a file exists, it will be overwritten. You can pass this parameter for any user except master and default. If you omit this parameter, then a new file name is generated.

data?​

IVdpData

Data for personalization. You can pass either dataSet or itemsData into this method.

options?​

ISaveProductOptions

Define how the personalization data should be applied.

Returns​

Promise<ISaveProductResult>

Returns a promise with a return-to-edit URL, userId, and stateId.

Example​

// Saving a product to the "t-shirt.st" file.
const savingResults = await editor
  .saveProduct("t-shirt")
  // If an error occurred while saving the product.
  .catch((error) =>
    console.error("Saving product failed with exception: ", error),
  );

// If the product is saved correctly, get the promise properties.
userId = savingResults.userId;
stateId = savingResults.stateId;
returnToEditUrl = savingResults.returnToEditUrl;
console.log("User " + userId + " successfully saved state " + stateId);

revertProduct()​

revertProduct(revertToinitial?): Promise<void>

Cancels all changes made by a user.

Parameters​

revertToinitial?​

boolean

Enables reverting the user changes to the initial product state. false allows for reverting to the print areas which were set by Surface.setPrintAreas() with updateRevertData set to true. true allows for reverting to the initial product despite the updateRevertData parameter. The default value is false.

Returns​

Promise<void>

undo()​

undo(): Promise<void>

Reverts the last user action on the canvas.

Returns​

Promise<void>

redo()​

redo(): Promise<void>

Recovers the last user action on the canvas, which was reverted by the Undo command/button.

Returns​

Promise<void>

loadUserInfo()​

loadUserInfo(data?, options?): Promise<void>

Populates a product with user data.

Parameters​

data?​

IUserInfo

An object holding key-value pairs. The key is a layer name or an in-string placeholder name without markers and extra symbols. The value is a text or barcode data you want to insert into it. If you omit this parameter, then the userInfo passed to the editor during the initial loadEditor call is used.

options?​

ILoadUserInfoOptions

Options defining how the user info should be reflected in the history. You can now skip adding these changes to the history as well as replace the last snapshot.

Returns​

Promise<void>

Remarks​

Warning! This method is time-consuming. For optimization, you can populate a product template when it is loading into the editor with autoLoadUserInfo https://customerscanvas.com/dev/editors/iframe-api/howto/user-info.html|autoLoadUserInfo enabled.

Example​

let data = {
  Name: "Alex Smith",
  Position: "Manager",
  ID: {
    BarcodeFormat: "EAN_8",
    BarcodeValue: "1234567",
  },
};

// Load the web-to-print editor.
let editor = await CustomersCanvas.IframeApi.loadEditor(
  iframe,
  productDefinition,
  configuration,
);

// Populate the product with user data.
editor.loadUserInfo(data);

validateUserInfo()​

validateUserInfo(data): Promise<IValidationResult>

Validates the provided user info.

Parameters​

data​

IUserInfo

An object holdsing key-value pairs. The key is a layer name or an in-string placeholder name without markers and extra symbols. The value is a text or barcode date you want to load into the editor.

Returns​

Promise<IValidationResult>

Example​

  const data = {
      "Name": "Alex Smith",
      "Position": "Manager",
      "ID": {
          "BarcodeFormat": "EAN_8",
          "BarcodeValue": "1234567"
      }
  };

  // Load the web-to-print editor.
  const editor = await CustomersCanvas.IframeApi.loadEditor(iframe, productDefinition, configuration))
                       // If an error occurred while loading the editor.
                       .catch(e => console.log(e));

  // Validate userInfo.
  const validationResults = await editor.validateUserInfo(data);
  if (validationResults.error) {
      // Output the error.
      console.error(validationResults);
      return;
  }

  // Populate the product with valid user data.
  editor.loadUserInfo(data);

getUnchangedItems()​

getUnchangedItems(): Promise<IUnchangedItems>

Gets a list of layers that have not been personalized by the user.

Returns​

Promise<IUnchangedItems>

A list of layers that have not been personalized by the user.

Remarks​

The resulting list will only contain text items and placeholders that were not changed by the user.

Example​

const unchangedItems = editor.getUnchangedItems();

if (unchangedItems.items.length > 0) {
  unchangedItems.items.forEach(function (logItems) {
    console.log(logItems);
  });
} else {
  console.log("There are no unchanged items");
}

subscribe()​

subscribe(event, handler): void

Links an event with a handler function.

Parameters​

event​

string

The event to link the handler function with.

handler​

(...args) => void

The handler function to link with the given event.

Returns​

void

Remarks​

The Events object contains the supported events.

Example​

const editor = await CustomersCanvas.IframeApi.loadEditor(
  iframe,
  productDefinition,
);
editor.subscribe(
  CustomersCanvas.IframeApi.PostMessage.Events.BoundsNotification,
  (args) => {
    console.log("BoundsNotification was triggered.");
    console.log(JSON.stringify(args, null, 4));
  },
);
editor.subscribe(
  CustomersCanvas.IframeApi.PostMessage.Events.PrintAreaBoundsChanged,
  (args) => {
    console.log("PrintAreaBoundsChanged");
    console.log(args);
  },
);

getProduct()​

getProduct(): Promise<Product>

Returns the product currently loaded in the editor.

Returns​

Promise<Product>

The product loaded in the editor.

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 an error occurred while getting the product or adding a back side to the postcard.
  .catch(function (error) {
    console.error("Adding surface failed with exception: ", error);
  });

replaceInterpolationPlaceholders()​

replaceInterpolationPlaceholders(): void

Returns​

void

applyProductTheme()​

applyProductTheme(theme, options?): Promise<void>

Applies a color theme to the loaded product.

Parameters​

theme​

any

The name of a color theme defined for the configuration or a theme definition.

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((error) =>
    console.error("The editor failed to load with an exception: ", error),
  );

// 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 to the history.
  {
    addToHistory: false,
  },
);

eval()​

eval(code, ...args): Promise<any>

Parameters​

code​

string | Function

args​

...any[]

Returns​

Promise<any>

dispose()​

dispose(): void

Releases all resources used by the editor.

Returns​

void

getSelectedItems()​

getSelectedItems(): Promise<Item[]>

Gets an array of selected design elements.

Returns​

Promise<Item[]>

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);
}

selectItems()​

selectItems(items): Promise<void>

Selects the specified design elements on the current surface.

Parameters​

items​

CcItem[]

An array of objects that contain design element names.

Returns​

Promise<void>

Remarks​

You can call (Editor:class).getSelectedItems to access the items.

Example​

editor.selectItems([
  {
    name: "Contact",
  },
  {
    name: "Address",
  },
]);

clearSelection()​

clearSelection(): Promise<void>

Deselects design elements on the current surface.

Returns​

Promise<void>

Example​

editor.clearSelection();

selectAllItems()​

selectAllItems(): Promise<void>

Selects all design elements on the current surface.

Returns​

Promise<void>

Remarks​

You can call (Editor:class).getSelectedItems to access the items.

Example​

editor.selectAllItems();

setViewerSettings()​

setViewerSettings(settings): Promise<unknown>

Changes Parameters of displaying the propuct on the canvas.

Parameters​

settings​

IViewerSettings

An object defining the appearance of the canvas.

Returns​

Promise<unknown>

Example​

// Changing the zoom and scroll position.
editor
  .setViewerSettings({
    zoom: 0.1,
    zoomMode: "bestFit",
    scrollPosition: { x: 0, y: 0 },
  })
  .catch((error) => {
    console.error(
      "Changing the canvas settings failed with exception: ",
      error,
    );
  });

openGallery()​

openGallery(params?, action?): Promise<unknown>

Opens the Asset Manager with the listed asset tabs to add a new image to the design.

Parameters​

params?​

Parameters defining the appearance of the Asset Manager. In the params.tabs array, pass the names of the required asset sources.

tabs?​

string[]

action?​

"layout" | "fillPlaceholders"

An action that should be applied to the product, either "layout" to change layouts or "fillPlaceholders" to automatically fill out image placeholders. By default, the Action Manager opens to add an image to the design.

Returns​

Promise<unknown>

Examples​

let editor = await CustomersCanvas.IframeApi.loadEditor(
  iframe,
  product,
  config,
);
editor.openGallery({ tabs: ["My Files", "Deposit Photos"] });
editor.openGallery({ tabs: ["Layouts"] }, "layout");

openGalleryForBackground()​

openGalleryForBackground(params?): Promise<unknown>

Opens the Asset Manager to select an image for the background layer.

Parameters​

params?​

Parameters defining the appearance of the Asset Manager. In the params.tabs array, pass the names of the required asset sources.

tabs?​

string[]

Returns​

Promise<unknown>

Example​

let editor = await CustomersCanvas.IframeApi.loadEditor(
  iframe,
  product,
  config,
);
editor.openGalleryForBackground({ tabs: ["Backgrounds"] });

openGalleryForItem()​

openGalleryForItem(name, params?): Promise<void>

Opens the Asset Manager to select an image for the specified item.

Parameters​

name​

string

The name of the image you want to change.

params?​

Parameters defining the appearance of the Asset Manager. In the params.tabs array, pass the names of the required asset sources.

tabs?​

string[]

Returns​

Promise<void>

Example​

let editor = await CustomersCanvas.IframeApi.loadEditor(
  iframe,
  product,
  config,
);
editor.openGalleryForItem("Company Logo", { tabs: ["Logos"] });

setThemeConfiguration()​

setThemeConfiguration(conf): Promise<void>

Changes a preloader image and the primary theme color.

Parameters​

conf​

IThemeConfiguration

Defines the primary color and a new image for the standard preloader.

Returns​

Promise<void>

Example​

let editor = await CustomersCanvas.IframeApi.loadEditor(
  iframe,
  product,
  config,
);
await editor.setThemeConfiguration({ primaryColor: "rgb(120, 24, 123)" });

updateConfiguration()​

updateConfiguration(config): Promise<void>

Parameters​

config​

IConfiguration

Returns​

Promise<void>

toggleObjectInspector()​

toggleObjectInspector(): Promise<void>

Changes the visibility of the Object Inspector. It allows for displaying or hiding the Object Inspector during the editing process.

Returns​

Promise<void>

Example​

let editor = await CustomersCanvas.IframeApi.loadEditor(
  iframe,
  product,
  config,
);
await editor.toggleObjectInspector();
Was this page helpful?