---
title: "Toolbox | Customer's Canvas On-Premises"
canonical: "https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/editor-configuration/toolbox/"
---

# Toolbox

> The Toolbox appears in the [advanced editing mode](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/editor-configuration/simple-and-advanced-modes.md) and contains buttons for adding design elements to products at runtime. The Toolbox may contain both standard buttons and custom buttons. The [standard buttons](#defining-the-standard-buttons) allow for adding elements to the center of the canvas. However, you can [change their default appearance](#custom-design-elements) and specify the location, size, content, permissions, and other properties. You can configure [buttons for adding images](#defining-buttons-to-open-the-asset-manager) so that your users open the Asset Manager in the desired mode. The [custom buttons](#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](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/editor-configuration/reference.md#objectInspectorPosition) property to `"Right"`.

![The Toolbox is on the left side of the canvas.](images/ToolboxFromLeft.png)

## Defining the Standard Buttons

You can set up the Toolbox through either the **~/Configuration/clientConfig.json** file or the [IConfiguration](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/reference/design-editor-iframe/interfaces/ConfigurationInterfaces.IConfiguration.md) 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.

```json title="Defining standard buttons"
{
    "widgets": {
        "Toolbox": {
            "buttons": [ "Text", "Image" ]
        }
    }
}
```

Here, the buttons array contains the [standard button actions](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/reference/design-editor-iframe/types/WidgetConfigurationInterfaces.ILeftToolbarConfig.ButtonAction.md) `"Text"` and `"Image"`. You can also define buttons by using the [IButton](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/reference/design-editor-iframe/interfaces/WidgetConfigurationInterfaces.ILeftToolbarConfig.IButton.md) interface and rewrite the previous example to the following equivalent definition.

```json title="Defining view IButton equivalent"
{
    "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](#specifying-the-toolbox-captions) 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:

```json title="Defining a button group"
{
    "widgets": {
        "Toolbox": {
            "buttons": [
                {
                    "translationKey": "Toolbox.TEXT",
                    "translationKeyTitle": "Toolbox.TITLE_ADD_TEXT",
                    "iconClass": "cc-icon-add-text",
                    "buttons": ["Text", "BoundedText"]
                }
            ]
        }
    }
}
```

![The group of text buttons in the Toolbox.](images/ToolboxGroup.png)

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:

```css {3,13} title="Toolbox icons"
.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](#defining-the-standard-buttons) 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 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| ![Add text.](images/ToolboxIcon01.png) | cc-icon-add-text | ![Add rich text.](images/ToolboxIcon02.png) | cc-icon-rich-text | ![Add images.](images/ToolboxIcon03.png) | cc-icon-add-image |
| ![Add shapes.](images/ToolboxIcon04.png) | cc-icon-add-shape | ![Add lines.](images/ToolboxIcon05.png) | cc-icon-line | ![Add rectangles.](images/ToolboxIcon06.png) | cc-icon-rectangle |
| ![Add ellipses.](images/ToolboxIcon07.png) | cc-icon-ellipse | ![Add barcodes.](images/ToolboxIcon08.png) | cc-icon-linear-code | ![Add QR codes.](images/ToolboxIcon09.png) | cc-icon-qr-code |
| ![Add backgrounds.](images/ToolboxIcon10.png) | cc-icon-background | ![Add layouts.](images/ToolboxIcon11.png) | cc-icon-layout | ![Add layouts.](images/ToolboxIcon12.png) | cc-icon-barcode-data-matrix |

For reference, you can download [fonts with Design Editor icons](pathname:///files/cc-icons.zip).

If you need to apply custom icons, refer to the [icons](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/customization/icons.md) 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:

```css
@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:

```js
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.

```json
{
    "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](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/product-definition/post-press-finishing-layers.md) 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:

```js
let 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>`

![Defining channel containers.](images/ToolboxContainer.png)

Now, you can define a different Toolbox for the `foil` container.

```json
{
    "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](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/editor-configuration/image-manager.md) 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.

```json title="Defining an Asset Manager tab"
{
    "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.

```json
{
    "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).

```json
{
    "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`.

```json
{
    "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](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/howto/user-info.md) feature. To post-process templates, you can use the [Web API for personalized rendering](https://customerscanvas.com/docs/on-premises/design-editor/apis/personalized-rendering.md).

To enable a button for adding custom design elements, you need to specify the [IButton.itemConfig](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/reference/design-editor-iframe/interfaces/WidgetConfigurationInterfaces.ILeftToolbarConfig.IButton.md) object and the corresponding custom action in the Toolbox. In `itemConfig`, you can specify the name and `isVariable` properties to [post-process a product](#retrieving-a-list-of-variable-items). The following example illustrates how you can define a custom text field and a custom image - `ClientName` and `Logo` - in the **clientConfig.json** file:

```json
{
    "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](#custom-images) | [IImageItemData](https://customerscanvas.com/docs/on-premises/design-atoms-js/reference/design-atoms-interfaces/IImageItemData.md) | angle, blendMode, borderColor, borderWidth, height, imagePermissions, imageUrl, isVariable, itemPermissions, location, manipulationPermissions, name, opacity, overlayColor, visualizationPermissions, width |
| [Image placeholders](#custom-image-placeholders) | [IPlaceholderItemData](https://customerscanvas.com/docs/on-premises/design-atoms-js/reference/design-atoms-interfaces/IPlaceholderItemData.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](#custom-text) | [IPlainTextItemData](https://customerscanvas.com/docs/on-premises/design-atoms-js/reference/design-atoms-interfaces/IPlainTextItemData.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](#custom-bounded-text) | [IBoundedTextItemData](https://customerscanvas.com/docs/on-premises/design-atoms-js/reference/design-atoms-interfaces/IBoundedTextItemData.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](#custom-barcodes) | [IBarcodeItemData](https://customerscanvas.com/docs/on-premises/design-atoms-js/reference/design-atoms-interfaces/IBarcodeItemData.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/on-premises/design-editor/iframe-api/reference/design-editor-iframe/interfaces/ConfigurationInterfaces.IDefaultItemsConfig.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/on-premises/design-editor/iframe-api/editor-configuration/element-names.md#creating-new-items) 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:` 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, 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.

```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,
                    "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.

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

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

```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

    ```json title="EAN_8"
    "barcodeContent": {
        "barcodeFormat": "EAN_8",
        "barcodeValue": "1234567"
    }
    ```

-   EAN_13

    ```json title="EAN_13"
    "barcodeContent": {
        "barcodeFormat": "EAN_13",
        "barcodeValue": "123456789012"
    }
    ```

-   IMB

    ```json title="IMB"
    "barcodeContent": {
        "barcodeFormat": "EAN_13",
        "barcodeValue": "123456789012"
    }
    ```

-   QrPhone

    ```json title="QrPhone"
    "barcodeContent": {
        "barcodeFormat": "QR_CODE",
        "barcodeSubType": "Phone",
        "phone": "+15551234567"
    }
    ```

-   QrUrl

    ```json title="QrUrl"
    "barcodeContent": {
        "barcodeFormat": "QR_CODE",
        "barcodeSubType": "Url",
        "url": "example.com"
    }
    ```

-   QrVCard

    ```json title="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/on-premises/design-editor/iframe-api/reference/design-editor-iframe/classes/ObjectModel.Product.md#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.

```js
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/on-premises/design-editor/apis/state-files.md#get-variable-items-from-a-state-file).

## 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](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/reference/design-editor-iframe/interfaces/ConfigurationInterfaces.IDefaultItemsConfig.md) 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](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/reference/design-editor-iframe/interfaces/ConfigurationInterfaces.IConfiguration.md).

```js
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.

```js
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.

```json
{
  "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`.

```json
{
    "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.

```json
{
    "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](https://customerscanvas.com/docs/on-premises/design-editor/iframe-api/reference/design-editor-iframe/classes/RpcTypes.Events.md#custombuttonclicked) is fired. To handle this event, you need to subscribe to it as follows:

```js
const 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)); 
})
```