When implementing variable data printing, you may want to provide your users with a set of custom design elements, for example, a text box for the client name or an image placeholder for the company logo. You can predefine the name, location, size, content, and other properties of a single element being added to the canvas. These elements can be specified through Toolbox buttons. For runtime personalization, Customer's Canvas provides the Load user info feature. To post-process templates, you can use the Web API for personalized rendering.
To enable a custom button in the Toolbox, you need to specify the IButton.itemConfig object and the corresponding custom action. In itemConfig, you can specify the name and isVariable properties to post-process a product. The following example illustrates how you can define a custom text field and a custom image - ClientName and Logo - in the clientConfig.json file:
{
"widgets": {
"Toolbox": {
"buttons": [
{
"action": "Text",
"iconClass": "cc-icon-add-text",
"itemConfig": {
"name": "ClientName",
"isVariable": true,
"text": "Client"
}
},
{
"action": "CustomImage",
"iconClass": "cc-icon-add-image",
"itemConfig": {
"name": "Logo",
"isVariable": true,
"imageUrl": "public:logos/company.png",
"width": 144,
"opacity": 0.85
}
}
]
}
}
}
The following table details custom design elements, an interface defining them, and their properties that you can pass to itemConfig when configuring the Toolbox.
| Elements | Interfaces | Properties |
|---|---|---|
| Images | IImageItemDefaultConfig | angle, blendMode, borderColor, borderWidth, height, imagePermissions, imageUrl, isVariable, itemPermissions, location, manipulationPermissions, name, opacity, overlayColor, visualizationPermissions, width |
| Image placeholders | IPlaceholderItemDefaultConfig | allowedSubfolder, allowedTabs, angle, blendMode, borderColor, borderWidth, contentImageUrl, contentPermissions, contentResizeMode, fillColor, fixedStubContentSize, height, isCoverMode, isStubContent, isVariable, itemPermissions, location, manipulationPermissions, name, opacity, placeholderPermissions, visualizationPermissions, width |
| Plain point text | ITextConfig | alignment, angle, blendMode, borderColor, borderWidth, color, fillColor, font, horizontalScale, isVariable, isVertical, itemPermissions, location, manipulationPermissions, maxLineCount, maxLineLength, name, opacity, shadow, stroke, text, textPermissions, underline, verticalScale, visualizationPermissions |
| Bounded text | ITextConfig | alignment, angle, blendMode, borderColor, borderWidth, color, fillColor, font, height, horizontalScale, isVariable, isVertical, itemPermissions, location, manipulationPermissions, maxLineCount, maxLineLength, name, opacity, overflowStrategy, paragraphSettings, shadow, stroke, text, textPermissions, textShrinkMode, underline, verticalAlignment, verticalScale, visualizationPermissions, width, wrappingMargin |
| Barcodes | IBarcodeDefaultConfig | angle, blendMode, barcodeContent, barcodePermissions, borderColor, borderWidth, fillColor, height, isVariable, itemPermissions, location, manipulationPermissions, name, opacity, overlayColor, visualizationPermissions, width |
IButton.itemConfig allows you to specify all properties supported by IDefaultItemsConfig, and when you define itemConfig, it overrides the corresponding properties of the default configuration.
Note that you can omit the names of custom elements and enable the nameDialogEnabled button property to allow your users to define these names when editing products on the canvas.
For more details about the Toolbox, you can refer to the Customizing the Toolbox topic.
To predefine an image, add a button with the CustomImage action to the Toolbox. For this button type, you must define the imageUrl property in itemConfig. This property may contain a direct URL to images, or refer to private user images or images in the public gallery. You need to specify the image source in the value:
user: prefix, for example, "user:myLogo.jpg".public: prefix, for example, "public:car_logos/ford.jpg".http: or https: protocol name, for example, "https://example.com/company.svg".When you specify the width and height properties, the image fits the corresponding rectangle. Otherwise, the image fits the print area.
The following config allows your users to add the predefined image to the upper-left corner of the product.
{
"widgets": {
"Toolbox": {
"buttons": [{
"action": "CustomImage",
"iconClass": "cc-icon-add-image",
"itemConfig": {
"name": "ProductThumbnail",
"isVariable": true,
"imageUrl": "https://example.com/thumbnails/item1200.png",
"borderWidth": 1,
"blendMode": "multiply",
"width": 72,
"height": 36,
"location": {
"originX": "left",
"originY": "top",
"x": 10,
"y": 10
}
}
}]
}
}
}
To predefine an image placeholder, add a button with the CustomPlaceholder action to the Toolbox. Customer's Canvas allows you to predefine normal, empty, and stub placeholders. To enable the content or the stub image, define the contentImageUrl property.
{
"widgets": {
"Toolbox": {
"buttons": [{
"iconClass": "cc-icon-select-image-top-toolbar",
"action": "CustomPlaceholder",
"itemConfig": {
"name": "Custom Placeholder",
"isVariable": false,
"allowedSubfolder": "europe_photos",
"allowedTabs": [ "Public" ],
"contentImageUrl": "public:europe_photos/morning_cafe.jpg",
"isStubContent": true,
"fixedStubContentSize": true,
"isCoverMode": false,
"contentResizeMode": "fit",
"width": "25%",
"height": "55%",
"placeholderPermissions": {
"allowEditContent": true,
"showSelectButton": true,
"showHandleButton": true
},
"contentPermissions": {
"imagePermissions": {
"allowChangeImage": true,
"allowEditImage": true
}
}
}
}]
}
}
}
To predefine plain point text, add a button with the Text or PointText action to the Toolbox. In itemConfig, the text property defines the content of the design element.
In the following example, we specify the colors, font properties, and the maximum number of allowed lines and characters in a line.
{
"widgets": {
"Toolbox": {
"buttons": [{
"action": "Text",
"iconClass": "cc-icon-add-text",
"itemConfig": {
"name": "CustomerName",
"isVariable": true,
"text": "Customer",
"color": "rgb(255, 0, 0)",
"fillColor": "rgba(200, 200, 200, 0.4)",
"font": {
"postScriptName": "Impact",
"size": 12,
"fauxBold": true,
"fauxItalic": true
},
"maxLineCount": 1,
"maxLineLength": 15,
"shadow": {
"color": "rgb(0, 0, 200)",
"size": 0.4,
"angle": 45,
"distance": 2
},
"stroke": {
"size": 0.3
},
"underline": true,
"location": {
"originX": "center",
"originY": "top",
"x": "50%",
"y": "10%"
}
}
}]
}
}
}
To predefine a bounded text element, add a button with the BoundedText action to the Toolbox. In itemConfig, the text property defines the content of the design element.
The overflowStrategy and textShrinkMode properties allow you to enable the copyfitting feature if your users will edit the predefined element.
In the following example, we configure a button for adding a description to the bottom of the print area.
{
"widgets": {
"Toolbox": {
"buttons": [{
"action": "BoundedText",
"iconClass": "cc-icon-rich-text",
"itemConfig": {
"name": "Description",
"isVariable": true,
"text": "Lorem ipsum dolor\n sit amet, consectetuer\n adipiscing elit",
"height": 72,
"width": 100,
"overflowStrategy": "FitToWidth",
"textShrinkMode": "size",
"alignment": "center",
"verticalAlignment": "center",
"angle": -10,
"color": "rgb(255, 0, 0)",
"font": {
"postScriptName": "Impact",
"size": 12
},
"stroke": {
"size": 0.3
},
"location": {
"originX": "center",
"originY": "bottom",
"x": "50%",
"y": "100%"
}
}
}]
}
}
}
To predefine a barcode, add a button with the CustomBarcode action to the Toolbox. For this button type, you must define the barcodeContent object in itemConfig. The required properties of the barcodeContent depend on the barcode format:
"barcodeContent": {
"barcodeFormat": "EAN_8",
"barcodeValue": "1234567"
}
"barcodeContent": {
"barcodeFormat": "EAN_13",
"barcodeValue": "123456789012"
}
"barcodeContent": {
"barcodeFormat": "IMB",
"barcodeValue": "12345678901234567890"
}
"barcodeContent": {
"barcodeFormat": "QR_CODE",
"barcodeSubType": "Phone",
"phone": "+15551234567"
}
"barcodeContent": {
"barcodeFormat": "QR_CODE",
"barcodeSubType": "Url",
"url": "example.com"
}
{
"widgets": {
"Toolbox": {
"buttons": [{
"action": "CustomBarcode",
"iconClass": "cc-icon-qr-code",
"itemConfig": {
"name": "VCard",
"isVariable": true,
"barcodeContent": {
"barcodeFormat": "QR_CODE",
"barcodeSubType": "VCard",
"email": "Charlotte@example.com",
"firstName": "Charlotte",
"lastName": "Henderson",
"mobilePhone": "1-770-555-6066",
"organization": "Independent Investors",
"phone": "1-800-555-6165",
"position": "Sales Manager",
"url": "example.com"
},
"barcodePermissions": {
"allowChangeBarcodeContent": false
},
"fillColor": "rgba(0, 0, 0, 0)",
"overlayColor": "rgb(0, 200, 0)",
"width": 72,
"location": {
"originX": "right",
"originY": "top",
"x": "95%",
"y": "5%"
}
}
}]
}
}
}
This example configures a button for adding a QR code containing a VCard. For QR codes, the editor generates a square design element with sides that are equal to the width property.
When you don't know in advance which fields should be personalized in a product, you can retrieve their names from the editor. The Product.getVariableItems method allows you to list design elements with the isVariable property set to true, as well as in-string and interpolation placeholders. Note that if you add a regular text element to the canvas and set its value in the {{<PLACEHOLDER_NAME>}} format at runtime, then this interpolation placeholder will be listed as a variable field.
CustomersCanvas.IframeApi.loadEditor(iframe, product)
.then(function(e){
editor = e;
});
function getVariableItems() {
editor.getProduct()
// If we have successfully obtained the product.
.then(function (product) {
return product.getVariableItems();
})
// If we have successfully obtained an item list.
.then(function (variableItems) {
if (variableItems.length)
console.log(variableItems);
else
console.log("This product contains no variable items.");
});
}
This method returns an array containing the name and type of variable fields. For text elements, the current value is also available.
You can also retrieve variable items from saved state files by using the Web API.