Toolbox
- 17 minutes to read
The Toolbox appears in the advanced editing mode and contains buttons for adding design elements to products at runtime. The Toolbox may contain both standard buttons and custom buttons. The standard buttons allow for adding elements to the center of the canvas. However, you can change their default appearance and specify the location, size, content, permissions, and other properties. You can configure buttons for adding images so that your users open the Asset Manager in the desired mode. The custom buttons allow you to perform your actions when the user clicks these buttons.
The position of the Toolbox depends on the UI theme. In the legacy Md and Bootstrap themes, this element appeared in the top row of the editor. In MdLight and Aurum, the Toolbox and Object Inspector appear on opposite sides of the canvas. Thus, if you need the Toolbox on the left side of the canvas, set the ObjectInspector.position property to "Right".
Defining the Standard Buttons
You can set up the Toolbox through either the ~/Configuration/clientConfig.json file or the IConfiguration interface. To enable buttons, you need to add them to the widgets.Toolbox.buttons array. These are the following predefined button types: Text, PointText, BoundedText, ArchedText, Image, Background, QrCode, LinearBarcode, DataMatrixBarcode, Line, Rectangle, Ellipse, Layout, and FillPlaceholders. You can add single buttons and organize them in groups. The following example illustrates how you can define two buttons in clientConfig.json for adding plain text and images.
{
"widgets": {
"Toolbox": {
"buttons": [ "Text", "Image" ]
}
}
}
Here, the buttons array contains the standard button actions "Text" and "Image". You can also define buttons by using the IButton interface and rewrite the previous example to the following equivalent definition.
{
"widgets": {
"Toolbox": {
"buttons": [
{
"translationKey": "Toolbox.ADD_TEXT",
"translationKeyTitle": "Toolbox.TITLE_ADD_TEXT",
"iconClass": "cc-icon-add-text",
"action": "Text"
},
{
"translationKey": "Toolbox.IMAGE",
"translationKeyTitle": "Toolbox.TITLE_ADD_IMAGE",
"iconClass": "cc-icon-add-image",
"action": "Image"
}
]
}
}
}
This interface allows you to set up captions, hints, icons, and button groups. Later, we will describe how you can specify button names in the Toolbox. Now, let us see how to organize buttons in groups. To perform this, define another buttons array instead of the action property. You can enable a button group for adding text elements as follows:
{
"widgets": {
"Toolbox": {
"buttons": [
{
"translationKey": "Toolbox.TEXT",
"translationKeyTitle": "Toolbox.TITLE_ADD_TEXT",
"iconClass": "cc-icon-add-text",
"buttons": ["Text", "BoundedText"]
}
]
}
}
}
By default, the Toolbox contains four button groups for adding text, images, shapes, and barcodes. To hide the Toolbox, set its enabled property to false.
Specifying the Toolbox Icons
To display icons, the Design Editor uses glyphs from the following fonts:
- MaterialIcons-Regular
- MaterialIcons-Regular-Extra
- new-cc-icons
In the distribution package, you can find \Resources\Generated\{version number}\design-editor-theme-aurum.css containing definitions of all CSS classes, which use these glyphs. When you open this file, you can find icon classes used in this topic:
.cc-icon-add-image:before,
.cc-icon-add-text:before, ... {
font-family: 'new-cc-icons' !important;
}
.cc-icon-add-image:before {
content: '\f101' !important;
}
.cc-icon-add-text:before {
content: '\f103' !important;
}
.cc-icon-background {
font-family: "Material Icons Extra";
}
.cc-icon-background:before {
content: "\eb62";
}
According to this definition, the Add image and Add text icons are in the new-cc-icons font, and the Background is in MaterialIcons-Regular-Extra. The classes refer to the icon glyphs by their character codes: f101, f103, and eb62. If needed, you can select other glyphs from these fonts. To specify an icon in the Toolbox, you need to set its class name to the iconClass property.
The following table contains the default Toolbox icons in the Aurum theme and their class names.
| Icon | Icon class | Icon | Icon class | Icon | Icon class |
 |
cc-icon-add-text |  |
cc-icon-rich-text |  |
cc-icon-add-image |
 |
cc-icon-add-shape |  |
cc-icon-line |  |
cc-icon-rectangle |
 |
cc-icon-ellipse |  |
cc-icon-linear-code |  |
cc-icon-qr-code |
 |
cc-icon-background |  |
cc-icon-layout |  |
cc-icon-barcode-data-matrix |
For reference, you can download fonts with Design Editor icons.
If you need to apply custom icons, refer to the Icons topic.
Custom icons
You can also create custom glyphs to implement new icons in the Toolbox. The Design Editor supports fonts in the TTF, WOFF, and WOFF2 formats. However, to enable the icons in all modern browsers, you can only add your glyphs to a WOFF2 file. After that, you can use them in custom styles. For example, let's assume that you have created a new glyph in a my-icons font to add images.
First, add your font my-icons.woff2 to the \Configuration\customCss\ folder.
Then, create a CSS file, for example, my-styles.css, in this folder:
@font-face {
font-family: 'my-icons';
src: url("my-icons.woff2") format("woff2");
}
.cc-icon-add-image:before {
font-family: 'my-icons' !important;
content: '\100' !important;
}
Finally, pass your styles in the editor's configuration:
let editorConfig = {
customStyle: "my-styles"
};
let editor = await CustomersCanvas.IframeApi.loadEditor(
document.getElementById("editorFrame"), product, editorConfig);
Specifying the Toolbox Captions
The Design Editor allows you to set up button captions and tooltips by using the translationKey and translationKeyTitle properties. These properties take string identifiers from the ~/Configuration/translations.json file. This file contains all the text that you can localize in the Design Editor UI. To change the captions, you need to find the Toolbox objects in this file and change the text for all the languages.
{
"en": {
"Toolbox": {
"ADD_IMAGE": "Add image",
"ADD_TEXT": "Add text",
...
},
...
},
"fr": {
"Toolbox": {
"ADD_IMAGE": "Ajouter une image",
"ADD_TEXT": "Ajouter du texte",
...
}
},
...
}
Note that the appearance of captions depends on the UI theme. For example, the captions of top-level buttons are not displayed in MdLight.
Defining Buttons for Channel Containers
Print areas have three basic containers for design elements: Background, Main, and Foreground. When users add design elements in the editor, they appear in the Main container. You can also add channel containers for spot colors and textures and define different toolboxes for them.
For example, you can specify a texture container in a product definition as follows:
var productDefinition = {
surfaces: [{
printAreas: [{
designFile: "postcard",
containers: [{
name: "foil",
texture: "texture.jpg",
type: "texture"
}]
}]
}]
};
As an alternative, you can specify this container within the postcard.psd template. To perform this, place the image on which you want the texture to appear in a new layer group and specify the following markers in the group name: <CN_foil><TFP_texture.jpg>
Now, you can define a different Toolbox for the foil container.
{
"widgets": {
"Toolbox": {
"buttons": [ "Text", "Image" ],
"containerToolboxes": {
"foil": {
"buttons": [ "Image" ]
}
}
}
}
}
Here, we define two buttons for adding plain text and images to the Main container and a button for adding images to the foil container.
Defining Buttons to Open the Asset Manager
Opening a Single Tab
When you enable the standard Image button, you allow your users to add images from any tab defined in the AssetManager.tabs array. To restrict the number of asset tabs available to your users, you can specify their names in the tabs array for a single button. The following example illustrates how you can only enable the Public Files tab for adding images through the Toolbox.
{
"widgets": {
"Toolbox": {
"buttons": [{
"action": "Image",
"iconClass": "cc-icon-add-image",
"tabs": [ "Public Files" ]
}]
}
}
}
Selecting Backgrounds
You can set up your gallery so that it displays backgrounds for user products on a separate tab. The following example configures the Toolbox and the Asset Manager to display backgrounds.
{
"assetSources": {
"Background Images": {
"type": "PublicSource",
"rootCategory": { "name": "Backgrounds" }
}
},
"widgets": {
"AssetManager": {
"tabs": [{
"name": "Background Tab",
"assetSourceInstance": "Background Images",
"iconClassName": "cc-icon-add-image",
"controls": { "insertToAllButtonEnabled": true }
}]
},
"Toolbox": {
"buttons": [{
"action": "Background",
"translationKey": "Toolbox.CHANGE_BACKGROUND",
"translationKeyTitle": "Toolbox.TITLE_CHANGE_BACKGROUND",
"iconClass": "cc-icon-background",
"tabs": [ "Background Tab" ]
}]
}
},
...
}
When defining the asset source, we set the rootCategory name to "Backgrounds", which means that the background images are in the ..\assets\images\Backgrounds\ folder. The insertToAllButtonEnabled property enables the Insert to all button, which allows your users to apply the selected background to all product pages at once.
Instead, you can only add the standard button Background to the Toolbox to allow for selecting backgrounds from available asset sources.
To allow your users to change the background image and color, you can set the onlyImage property to false. This property only applies to the Background action when defining a top-level button (not included in a group).
{
"widgets": {
"Toolbox": {
"buttons": [{
"action": "Background",
"translationKey": "Toolbox.CHANGE_BACKGROUND",
"translationKeyTitle": "Toolbox.TITLE_CHANGE_BACKGROUND",
"iconClass": "cc-icon-background",
"onlyImage": false
}]
}
}
}
Filling out Image Placeholders
You can allow your users to automatically fill out empty and stub image placeholders on a product. To perform this, use the FillPlaceholders button action. This action opens the Asset Manager and inserts the selected images into image placeholders that don't have any content. To enable the Select all button on an asset tab, set the selectAllButtonEnabled property to true.
{
"widgets": {
"AssetManager": {
"tabs": [{
"name": "My Files",
"assetSourceInstance": "My Files",
"iconClassName": "cc-icon-uploadable",
"controls": { "selectAllButtonEnabled": true }
}]
},
"Toolbox": {
"buttons": [{
"action": "FillPlaceholders",
"translationKey": "Toolbox.FILL_PLACEHOLDERS",
"translationKeyTitle": "Toolbox.TITLE_FILL_PLACEHOLDERS",
"iconClass": "cc-icon-select-image-top-toolbar",
"tabs": [ "My Files" ]
}]
}
},
...
}
In this example, we define the custom icon, caption, and the list of asset tabs. Instead, you can add the standard button FillPlaceholders to select images from available asset sources.
Custom Design Elements
When implementing variable data printing or predefining design elements, 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, the Design Editor provides the Load user info feature. To post-process templates, you can use the Web API for personalized rendering.
To enable a button for adding custom design elements, you need to specify the IButton.itemConfig object and the corresponding custom action in the Toolbox. 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": [{
"iconClass": "cc-icon-add",
"buttons": [
{
"action": "Text",
"iconClass": "cc-icon-add-text",
"itemConfig": {
"name": "CustomerName",
"isVariable": true,
"text": "Customer",
"textPermissions": {
"allowChangeText": false,
"allowChangeFontSize": false
},
"manipulationPermissions": {
"resizeGrips": {
"edge": false,
"corner": []
}
}
}
},
{
"action": "CustomImage",
"iconClass": "cc-icon-add-image",
"itemConfig": {
"name": "Logo",
"isVariable": true,
"imageUrl": "public:company.png",
"width": 62,
"location": {
"originX": "left",
"originY": "top",
"x": 10,
"y": 10
}
}
}
]
}]
}
}
}
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 | IImageItemData | angle, blendMode, borderColor, borderWidth, height, imagePermissions, imageUrl, isVariable, itemPermissions, location, manipulationPermissions, name, opacity, overlayColor, visualizationPermissions, width |
| Image placeholders | IPlaceholderItemData | 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 | IPlainTextItemData | 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 | IBoundedTextItemData | 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 | IBarcodeItemData | 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.
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:orhttps:protocol name, for example,"https://example.com/company.svg".
When you specify the width and height properties, the image fits the corresponding rectangle. Otherwise, two cases are possible. If the image is smaller than the print area, it will be uploaded with the actual size. If the image is larger than the design by any of the dimensions, then it will be proportionally resized to fit 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. The Design Editor 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 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": "EAN_13", "barcodeValue": "123456789012" }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 method allows you to list design elements with the isVariable property set to true, along with 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.
Default Parameters of Design Elements
In addition to the configured buttons, you can enable the same properties for all design elements being added to the canvas. These default parameters define the initial appearance and behavior of the elements. After your users have added the elements to the canvas, they can change the appearance of these elements.
The following example demonstrates how you can specify the default parameters of text, lines, and images through IConfiguration.
const configuration = {
defaultItemsConfig: {
text: {
font: {
postScriptName: "Impact",
size: "10%",
fauxBold: true,
fauxItalic: true
},
themeBinding: {
text: "MainColor"
},
isVertical: true,
verticalAlignment: "center",
overflowStrategy: "FitToWidth",
maxLineCount: 2,
maxLineLength: 20
},
line: {
width: 3,
color: "rgb(255,0,0)",
linePermissions: {
allowChangeLineWidth: false
}
},
image: {
blendMode: "multiply",
effect: "blackAndTransparent",
manipulationPermissions: {
allowMoveHorizontal: false,
allowMoveVertical: false,
resizeGrips: {
edge: true,
corner: ["Arbitrary"]
}
}
}
}
};
CustomersCanvas.IframeApi.loadEditor(document.getElementById("editorFrame"),
productDefinition, configuration);
To apply default parameters to SVG images imported in the Shape mode, define them as the shape element.
const configuration = {
defaultItemsConfig: {
shape: {
borderWidth: 2,
fillColor: "cmyk(0%, 0%, 0%, 25%, 100%)",
shapePermissions: {
allowChangeBorderWidth: false
}
}
}
}
Note that default parameters may depend on the corresponding properties of widgets. For example, you can disallow your users to change the opacity of only images being added to the canvas if you set the allowOpacityChange permission for images to false. If you disable the Select opacity slider in the TopToolbar, you prevent your users from changing the opacity of all images and other design elements in their products.
{
"defaultItemsConfig": {
"image": {
"itemPermissions": {
"allowOpacityChange": false
}
}
},
"widgets": {
"TopToolbar": {
"opacitySliderEnabled": true
}
}
}
Inserting Images
When your design contains an image or a shape on the topmost layer, and you want to add another image, then it will be considered the background for the top layer and will be added with a smaller z-index to appear below.
If you want to change this behavior so that each newly added image appears on top of all the elements, you can use the widgets.Toolbox.insertOnTop parameter set to true.
{
"widgets": {
"Toolbox": {
"insertOnTop": true
}
}
}
Custom buttons
The custom buttons allow you to implement custom actions in the editor. When the user clicks these buttons, an event is fired that allows you to handle the button click.
To add such buttons to the Toolbox, define the customButtons array with objects that have the customAction button action, buttonId to track the button, and customData to pass any details within the event. The customData property may contain a single value or a JSON object. You can also specify a caption and a hint the same way as the regular buttons and an icon by its URL.
{
"Toolbox": {
"customButtons": [
{
"translationKey": "Menu",
"translationKeyTitle": "Toggle side menu",
"iconUrl": "https://www.pngrepo.com/png/88703/60/api.png",
"action": "customAction",
"buttonId": "apiButton",
"customData": "some-details"
}
],
...
}
}
When the user clicks this button, the CustomButtonClicked event is fired. To handle this event, you need to subscribe to it as follows:
var editor = await CustomersCanvas.IframeApi.loadEditor(
document.getElementById("editorFrame"), product, config);
editor.subscribe(CustomersCanvas.IframeApi.PostMessage.Events.CustomButtonClicked, (args) => {
console.log("Clicked the button ", args[0]);
console.log(JSON.stringify(args, null, 4));
})