Class: Editor
Represents the Design Editor.
Constructors
Constructor
new Editor(
iframe,postMessageClient,editorUrl,config?):Editor
Parameters
iframe
HTMLIFrameElement
postMessageClient
editorUrl
string
config?
Returns
Editor
Properties
commandManager
commandManager:
CommandManager
Performs operations on design elements, surfaces, print areas, and the entire product.
Accessors
version
Get Signature
get
staticversion():string
Returns
string
configuration
Get Signature
get configuration():
RuntimeConfiguration
Returns
Methods
getProofImages()
getProofImages(
options?,data?):Promise<IProofResult>
Renders proof images (72 DPI).
Parameters
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.
data?
Parameters of variable data printing. You can pass either dataSet or itemsData into this method.
Returns
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?
Parameters of the hi-res and preview images.
data?
Parameters of variable data printing. You can pass either dataSet or itemsData into this method.
Returns
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?
Data for personalization. You can pass either dataSet or itemsData into this method.
options?
Define how the personalization data should be applied.
Returns
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?
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?
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
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
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
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()
Returns the product currently loaded in the editor.
Returns
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()
Gets an array of selected design elements.
Returns
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
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
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
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();