Custom Design Elements

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:

clientConfig.json
{
    "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
                    }
                }
            ]
        }
    }
}

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, borderColor, borderWidth, height, imagePermissions, imageUrl, isVariable, itemPermissions, location, manipulationPermissions, name, opacity, overlayColor, visualizationPermissions, width
Image placeholders IPlaceholderItemDefaultConfig allowedSubfolder, allowedTabs, angle, 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, 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, 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, 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.

For more details about the Toolbox, you can refer to the Customizing the Toolbox topic.

Custom Images

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:

  • For user images, the value contains the user: prefix, for example, "user:myLogo.jpg".
  • For public images, the value contains the public: prefix, for example, "public:car_logos/ford.jpg".
  • If the image is stored on the Web, the value should contain either the 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.

clientConfig.json
{
    "widgets": {
        "Toolbox": {
            "buttons": [{
                "action": "CustomImage",
                "iconClass": "cc-icon-add-image",
                "itemConfig": {
                    "name": "ProductThumbnail",
                    "isVariable": true,
                    "imageUrl": "https://example.com/thumbnails/item1200.png",
                    "borderWidth": 1,
                    "opacity": 0.85,
                    "width": 72,
                    "height": 36,
                    "location": {
                        "originX": "left",
                        "originY": "top",
                        "x": 10,
                        "y": 10
                    }
                }
            }]
        }
    }
}

Custom Image Placeholders

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.

clientConfig.json
{
    "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
                        }
                    }
                }
            }]
        }
    }
}

Custom Text

To predefine plain point text, add a button with the Text 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.

clientConfig.json
{
    "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%"
                    }
                }
            }]
        }
    }
}

Custom Bounded Text

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.

clientConfig.json
{
    "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%"
                    }
                }
            }]
        }
    }
}

Custom Barcodes

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:

  • EAN_8
    "barcodeContent": {
        "barcodeFormat": "EAN_8",
        "barcodeValue": "1234567"
    }
    
  • EAN_13
    "barcodeContent": {
        "barcodeFormat": "EAN_13",
        "barcodeValue": "123456789012"
    }
    
  • QrPhone
    "barcodeContent": {
        "barcodeFormat": "QR_CODE",
        "barcodeSubType": "Phone",
        "phone": "+15551234567"
    }
    
  • QrUrl
    "barcodeContent": {
        "barcodeFormat": "QR_CODE",
        "barcodeSubType": "Url",
        "url": "example.com"
    }
    
  • QrVCard
    clientConfig.json
    {
        "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.

Retrieving a List of Variable Items

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.

JavaScript
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.

See Also

Manual

IFrame API Reference