Customer's Canvas is honored with a 2020 InterTech Technology Award! Learn more 

Customizing the Toolbox

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 with predefined properties. While the standard buttons allow for adding default elements to the center of the canvas, the custom buttons allow you to specify the location, size, content, permissions, and other properties of elements being added to the product. You can configure buttons for adding images so that your users open the Asset Manager in the desired mode.

The position of the Toolbox depends on the UI theme. In the Md and Bootstrap themes, this element appears in the top row of the editor. In MdLight, the Toolbox and Object Inspector appear on the 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".

The Toolbox is on the left side of the canvas.

This topic dwells on how you can configure buttons in the Toolbox.

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, RichText, Image, Background, QrCode, LinearBarcode, 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
{
    "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.

json
{
    "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 icons and 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:

json
{
    "widgets": {
        "Toolbox": {
            "buttons": [
                {
                    "translationKey": "Toolbox.TEXT",
                    "translationKeyTitle": "Toolbox.TITLE_ADD_TEXT",
                    "iconClass": "cc-icon-add-text",
                    "buttons": ["Text", "BoundedText", "RichText"]
                }
            ]
        }
    }
}

The group of text buttons in the Toolbox.

By default, the Toolbox contains four button groups for adding text, images, shapes, and barcodes. To hide the Toolbox, set its disabled property to true.

Specifying the Toolbox Icons

To change or add new icons to the Toolbox, you need to edit the Customer's Canvas source code. You can download the sources in CustomersCanvasSrc.zip from your account.

Customer's Canvas uses glyphs from fonts in the \src\design-editor\styles\ControlStyles\fonts folder as icons. The \src\design-editor\styles\ControlStyles\sp-icons.less file contains definitions of classes that use these glyphs. If you open this file, you can find icon classes that we used in the previous examples:

less
.cc-icon-add-image:extend(.cc-icon) {
    &:before {
        content: "\e3f4";
    }
}

.cc-icon-add-text:extend(.cc-icon-extra) {
    &:before {
        content: "\eb4d";
    }
}

According to this definition, the Add image icon is in the MaterialIcons-Regular font, and Add text is in MaterialIcons-Regular-Extra. The classes refer to the glyphs by their character codes. 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 and their class names.

Icon Icon class Icon Icon class Icon Icon class
Add text. cc-icon-add-text Add rich text. cc-icon-rich-text Add images. cc-icon-add-image
Add shapes. cc-icon-add-shape Add lines. cc-icon-line Add rectangles. cc-icon-rectangle
Add ellipses. cc-icon-ellipse Add barcodes. cc-icon-linear-code Add QR codes. cc-icon-qr-code
Add backgrounds. cc-icon-background Add layouts. cc-icon-layout

You can also add new glyphs to these fonts to implement new icons in the Toolbox. To enable the icons in all supported browsers, add corresponding glyphs to TTF, WOFF, and either SVG or WOFF2 files.

Specifying the Toolbox Captions

Customer's Canvas 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 Customer's Canvas 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.

For more details about the localization of the editor, you can refer to the Localization of Customer's Canvas topic.

Defining the Custom Buttons

You can perform more detailed customization of the Toolbox and specify the name, content, location, and other properties that will be assigned to design elements when your users add them to the canvas. Thus, you can predefine a button set and allow your users to add elements that have hard-coded content or can be personalized by using the Web API.

To enable custom buttons, you need to define the corresponding action and itemConfig in the buttons array. Customer's Canvas provides the following custom button actions: CustomImage, CustomPlaceholder, CustomBarcode, Text, and BoundedText. An important feature of such buttons is that you can specify the name and isVariable properties, allowing you to implement variable data printing.

Now, let us see how you can predefine the design elements.

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
                            }
                        }
                    }
                ]
            }]
        }
    }
}

Here, we define two buttons for adding a text element and an image. Your users will be unable to change the content and size of this text after they add it to the canvas. For the image, we specified the initial width and location, but your users are free to change, resize, and relocate it.

For both elements, we defined names and set the isVariable property to true. The IFrame API allows you to get a list of such elements for further processing by using the getVariableItems method.

You can find more details about the custom buttons in the Custom Design Elements topic.

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:

JavaScript
var productDefinition = {
    surfaces: [{
        printAreas: [{
            designFile: "postcard",
            containers: [{
                name: "foil",
                texture: "texture.jpg",
                type: "texture"
            }]
        }]
    }]    
};

As an alternative, you can specify this container right in 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.

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 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
{
    "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 that allows your users to apply the selected background to all product pages at once.

As an alternative, you can only add the predefined action Background to the Toolbox to allow for selecting backgrounds from available asset sources.

Filling out Image Placeholders

You can allow your users to automatically fill out empty and stub image placeholders on the 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 the 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.

See Also

Manual

IFrame API Reference