Meet us at PRINT 19. Chicago, IL. Oct. 3 - 5.

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.

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, BoundedText, RichText, Image, Background, QrCode, LinearBarcode, Line, Rectangle, Ellipse, and Layout. 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
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

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>

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 for Asset Tabs

Now, let us see how you can configure the Toolbox to open a certain tab of your gallery.

When you enable the standard Image button, you allow your users to add images from any tab defined in either the AssetManager.tabs or GalleryDialog.tabs arrays. To specify the widget to open, you can use the defaultAssetSelectWidget property in clientConfig.json. Also, you can specify the widget for a single button by using the IGalleryButton.type property.

To restrict the number of asset tabs available to your users, you can list tab names in the tabs array. The following example illustrates how you can only enable the Public Files tab of the Asset Manager for adding images from the Toolbox.

json
{
    "widgets": {
        "Toolbox": {
            "buttons": [{
                "iconClass": "cc-icon-add-image",
                "action": "Image"
                "type": "AssetManager",
                "tabs": [ "Public Files" ]
            }]
        }
    }
}

See Also

Manual

IFrame API Reference