--- title: "Custom Design Elements" canonical: https://customerscanvas.com/docs/cc6/custom-design-elements.htm archived: true applies_to: - product: "Customer's Canvas On-Premises" - product: "Design Editor" versions: ["6.15.0", "6.x (may differ)"] --- **You’re viewing outdated documentation.** [View the latest Customer’s Canvas On-Premises documentation](https://customerscanvas.com/docs/on-premises/). # Custom Design Elements **Applies to:** Customer's Canvas On-Premises; Design Editor 6.15.0, 6.x (may differ) · **Archived documentation** 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](https://customerscanvas.com/docs/cc6/working-with-user-data.htm.md) feature. To post-process templates, you can use the [Web API for personalized rendering](https://customerscanvas.com/docs/cc6/web-api-for-rendering.htm.md). To enable a custom button in the **Toolbox**, you need to specify the [IButton.itemConfig](https://customerscanvas.com/docs/cc6/customerscanvas.baseeditor.configuration.ui.itoolboxconfigparsed.ibutton.htm.md) 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](https://customerscanvas.com/docs/cc6/customerscanvas.iframeapi.configuration.defaultconfig.iimageitemdefaultconfig.htm.md) | angle, blendMode, borderColor, borderWidth, height, imagePermissions, imageUrl, isVariable, itemPermissions, location, manipulationPermissions, name, opacity, overlayColor, visualizationPermissions, width | | Image placeholders | [IPlaceholderItemDefaultConfig](https://customerscanvas.com/docs/cc6/customerscanvas.iframeapi.configuration.defaultconfig.iplaceholderitemdefaultconfig.htm.md) | 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](https://customerscanvas.com/docs/cc6/customerscanvas.iframeapi.configuration.defaultconfig.itextconfig.htm.md) | 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](https://customerscanvas.com/docs/cc6/customerscanvas.iframeapi.configuration.defaultconfig.itextconfig.htm.md) | 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](https://customerscanvas.com/docs/cc6/customerscanvas.iframeapi.configuration.defaultconfig.ibarcodedefaultconfig.htm.md) | 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](https://customerscanvas.com/docs/cc6/customerscanvas.iframeapi.configuration.defaultconfig.htm.md), 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](https://customerscanvas.com/docs/cc6/defining-item-names.htm.md) 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](https://customerscanvas.com/docs/cc6/customizing-toolbox.htm.md) 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. ``` { "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 } } }] } } } ``` ## 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. ``` { "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** 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%" } } }] } } } ``` ## 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](https://customerscanvas.com/docs/cc6/copyfitting.htm.md) 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%" } } }] } } } ``` ## 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" } ``` - **IMB** ``` "barcodeContent": { "barcodeFormat": "IMB", "barcodeValue": "12345678901234567890" } ``` - **QrPhone** ``` "barcodeContent": { "barcodeFormat": "QR_CODE", "barcodeSubType": "Phone", "phone": "+15551234567" } ``` - **QrUrl** ``` "barcodeContent": { "barcodeFormat": "QR_CODE", "barcodeSubType": "Url", "url": "example.com" } ``` - **QrVCard** ``` { "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](https://customerscanvas.com/docs/cc6/customerscanvas.iframeapi.objectmodel.product.getvariableitems.htm.md) 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 `{{}}` 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](https://customerscanvas.com/docs/cc6/web-api-for-manipulating-states.htm.md). ## See Also ### Manual - [Customizing the Toolbox](https://customerscanvas.com/docs/cc6/customizing-toolbox.htm.md) - [Default Parameters of Design Elements](https://customerscanvas.com/docs/cc6/default-parameters-of-design-elements.htm.md) - [Working with User Data](https://customerscanvas.com/docs/cc6/working-with-user-data.htm.md) - [Web API for Personalized Rendering](https://customerscanvas.com/docs/cc6/web-api-for-rendering.htm.md) - [Web API for Manipulating State Files](https://customerscanvas.com/docs/cc6/web-api-for-manipulating-states.htm.md) ### IFrame API Reference - [IToolboxConfig](https://customerscanvas.com/docs/cc6/customerscanvas.baseeditor.configuration.ui.itoolboxconfigparsed.htm.md) - [IDefaultItemsConfig](https://customerscanvas.com/docs/cc6/customerscanvas.iframeapi.configuration.idefaultitemsconfig.htm.md)