Class Editor

Represents the Design Editor.

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 Editor class.

Properties

commandManager

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

Declaration
commandManager: CommandManager;
Property Value
Type Description
CommandManager

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

version

Declaration
static get version(): string;
Property Value
Type Description
string

Methods

applyProductTheme(theme, options)

Applies a color theme to the loaded product.

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

The name of a color theme defined for the configuration or a theme definition.
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(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
        });

clearSelection()

Deselects design elements on the current surface.

Declaration
clearSelection(): Promise<void>;
Returns
Type Description
Promise<void>
Examples
editor.clearSelection();

dispose()

Releases all resources used by the editor.

Declaration
dispose(): void;
Returns
Type Description
void

finishProductDesign(options, data)

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

Declaration
finishProductDesign(options?: Editor.IFinishProductDesignOptions, data?: Editor.IVdpData): Promise<Editor.IFinishDesignResult>;
Parameters
Type Name Description
IFinishProductDesignOptions options

Parameters of the hi-res and preview images.
IVdpData data

Parameters of variable data printing. You can pass either dataSet or itemsData into this method.
Returns
Type Description
Promise<Editor.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.
Examples
// 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);

getProduct()

Returns the product currently loaded in the editor.

Declaration
getProduct(): Promise<Product>;
Returns
Type Description
Promise<Product>

The product loaded in the editor.
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 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);
   });

getProofImages(options, data)

Renders proof images (72 DPI).

Declaration
getProofImages(options?: Editor.IGetProofImagesOptions, data?: Editor.IVdpData): Promise<Editor.IProofResult>;
Parameters
Type Name Description
IGetProofImagesOptions options

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.
IVdpData data

Parameters of variable data printing. You can pass either dataSet or itemsData into this method.
Returns
Type Description
Promise<Editor.IProofResult>

Returns an array of temporary links to proof images.
Examples
// 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;

getSelectedItems()

Gets an array of selected design elements.

Declaration
getSelectedItems(): Promise<Item[]>;
Returns
Type Description
Promise<Item[]>
Examples
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);
}

getUnchangedItems()

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

Declaration
getUnchangedItems(): Promise<Editor.IUnchangedItems>;
Returns
Type Description
Promise<Editor.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.

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

loadUserInfo(data, options)

Populates a product with user data.

Declaration
loadUserInfo(data?: Editor.IUserInfo, options?: Editor.ILoadUserInfoOptions): Promise<void>;
Parameters
Type Name Description
IUserInfo data

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.
ILoadUserInfoOptions options

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
Type Description
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 enabled.

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

openGallery(params, action)

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

Declaration
openGallery(params?: {
        tabs?: string[];
    }, action?: "layout" | "fillPlaceholders"): Promise<unknown>;
Parameters
Type Name Description
{ tabs?: string[]; } params

Parameters defining the appearance of the Asset Manager. In the params.tabs array, pass the names of the required asset sources.
"layout" | "fillPlaceholders" action

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
Type Description
Promise<unknown>
Examples

After you have defined the "My Files" and "Deposit Photos" asset sources, you can open the gallery with these tabs as follows:

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

You can also open the Action Manager to change product layouts as follows:

editor.openGallery({ tabs: ["Layouts"] }, "layout");

openGalleryForBackground(params)

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

Declaration
openGalleryForBackground(params?: {
        tabs?: string[];
    }): Promise<unknown>;
Parameters
Type Name Description
{ tabs?: string[]; } params

Parameters defining the appearance of the Asset Manager. In the params.tabs array, pass the names of the required asset sources.
Returns
Type Description
Promise<unknown>
Examples
let editor = await CustomersCanvas.IframeApi.loadEditor(iframe, product, config);
editor.openGalleryForBackground({ tabs: ["Backgrounds"] });

openGalleryForItem(name, params)

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

Declaration
openGalleryForItem(name: string, params?: {
        tabs?: string[];
    }): Promise<void>;
Parameters
Type Name Description
string name

The name of the image you want to change.
{ tabs?: string[]; } params

Parameters defining the appearance of the Asset Manager. In the params.tabs array, pass the names of the required asset sources.
Returns
Type Description
Promise<void>
Examples
let editor = await CustomersCanvas.IframeApi.loadEditor(iframe, product, config);
editor.openGalleryForItem("Company Logo", { tabs: ["Logos"] });

parseStringColor(colorString)

Declaration
parseStringColor(colorString: string): Promise<IColor>;
Parameters
Type Name Description
string colorString
Returns
Type Description
Promise<IColor>

redo()

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

Declaration
redo(): Promise<void>;
Returns
Type Description
Promise<void>

revertProduct(revertToinitial)

Cancels all changes made by a user.

Declaration
revertProduct(revertToinitial?: boolean): Promise<void>;
Parameters
Type Name Description
boolean revertToinitial

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

saveProduct(stateId, data, options)

Saves a product current state.

Declaration
saveProduct(stateId?: string, data?: Editor.IVdpData, options?: Editor.ISaveProductOptions): Promise<Editor.ISaveProductResult>;
Parameters
Type Name Description
string stateId

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.
IVdpData data

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

Define how the personalization data should be applied.
Returns
Type Description
Promise<Editor.ISaveProductResult>

Returns a promise with a return-to-edit URL, userId, and stateId.
Examples
// 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);

selectAllItems()

Selects all design elements on the current surface.

Declaration
selectAllItems(): Promise<void>;
Returns
Type Description
Promise<void>
Remarks

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

Examples
editor.selectAllItems();

selectItems(items)

Selects the specified design elements on the current surface.

Declaration
selectItems(items: CcItem[]): Promise<void>;
Parameters
Type Name Description
Item_2[] items

An array of objects that contain design element names.
Returns
Type Description
Promise<void>
Remarks

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

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

setThemeConfiguration(conf)

Changes a preloader image and the primary theme color.

Declaration
setThemeConfiguration(conf: IThemeConfiguration): Promise<void>;
Parameters
Type Name Description
IThemeConfiguration conf

Defines the primary color and a new image for the standard preloader.
Returns
Type Description
Promise<void>
Examples
let editor = await CustomersCanvas.IframeApi.loadEditor(iframe, product, config);
await editor.setThemeConfiguration({ primaryColor: "rgb(120, 24, 123)" });

setViewerSettings(settings)

Changes Parameters of displaying the propuct on the canvas.

Declaration
setViewerSettings(settings: Editor.IViewerSettings): Promise<unknown>;
Parameters
Type Name Description
IViewerSettings settings

An object defining the appearance of the canvas.
Returns
Type Description
Promise<unknown>
Examples
// 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);
    });

subscribe(event, handler)

Links an event with a handler function.

Declaration
subscribe(event: string, handler: (...args: any[]) => void): void;
Parameters
Type Name Description
string event

The event to link the handler function with.
(...args: any[]) => void handler

The handler function to link with the given event.
Returns
Type Description
void
Remarks

The Events object contains the supported events.

Examples

The following snippet subscribes to the Events.BoundsNotification event and outputs the event arguments to the console:

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

toggleObjectInspector()

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

Declaration
toggleObjectInspector(): Promise<void>;
Returns
Type Description
Promise<void>
Examples
let editor = await CustomersCanvas.IframeApi.loadEditor(iframe, product, config);
await editor.toggleObjectInspector();

undo()

Reverts the last user action on the canvas.

Declaration
undo(): Promise<void>;
Returns
Type Description
Promise<void>

updateConfiguration(config)

Declaration
updateConfiguration(config: IConfiguration): Promise<void>;
Parameters
Type Name Description
IConfiguration config
Returns
Type Description
Promise<void>

validateUserInfo(data)

Validates the provided user info.

Declaration
validateUserInfo(data: Editor.IUserInfo): Promise<Editor.IValidationResult>;
Parameters
Type Name Description
IUserInfo data

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