--- title: "Using the Image Gallery" canonical: https://customerscanvas.com/docs/cc4/using-image-gallery.htm archived: true applies_to: - product: "Customer's Canvas On-Premises" - product: "Design Editor" versions: ["4.4.25", "4.x (may differ)"] --- **You’re viewing outdated documentation.** [View the latest Customer’s Canvas On-Premises documentation](https://customerscanvas.com/docs/on-premises/). # Using the Image Gallery **Applies to:** Customer's Canvas On-Premises; Design Editor 4.4.25, 4.x (may differ) · **Archived documentation** This topic dwells on the Customer's Canvas image **Gallery**. The **Gallery** provides access to all images available to the user. In this topic: - The **Gallery** overview - Uploading files - Customizing the **Public files** collection - Configuring gallery tabs - Adding the **Layouts** tab - Adding the **Background** tab As an alternative to the **Image Gallery**, you can use the [Asset Manager](https://customerscanvas.com/docs/cc4/asset-manager.htm.md) for selecting images. ## The Gallery Overview When the user adds a new image to a product or replaces a previously added image, the **Gallery** is displayed. Right-click an image in the design or an image layer to see the **Item menu**. ![The image pop-up menu.](https://customerscanvas.com/docs/cc4/images/UsingImageGallery01.png) ![The layer's arrow pop-up menu.](https://customerscanvas.com/docs/cc4/images/UsingImageGallery02.png) Click **Select image** to see the **Gallery**. There are other ways to open the **Gallery**. Simply double-click an image, and in advanced editing mode, the **Gallery** is displayed when the user adds a new image to a design. The editing modes are discussed in the [Simple and Advanced Web-to-Print Editor Modes](https://customerscanvas.com/docs/cc4/simple-and-advanced-designer-modes.htm.md) topic. The **Gallery** interface is as it appears in the following screenshot. ![The Gallery.](https://customerscanvas.com/docs/cc4/images/UsingImageGallery03.png) The **Gallery** provides access to all images available to the user. In the screenshot above, there are four tabs, each of which corresponds to an image source: - The **My files** tab contains user-uploaded images; such images are available only for the user who uploaded them. - The **Public files** tab contains images available for all users. - The **Facebook** and **Instagram** tabs contain users' images from their Facebook or Instagram accounts, respectively. Customer's Canvas displays collections of **Facebook** and **Instagram** images in batches. If a collection contains more images than the tab displays, then the **More** button appears. In the previous screenshot, the **Public files** tab is selected. The images are divided into categories, and each category has the same name as the corresponding subfolder in the public gallery folder. The number of files in a category is displayed in parentheses after the category name. Also, there are two "special" categories, namely, **root** and **all**. The following screenshot shows the **My files** tab, which is the user's private tab in the **Gallery**. ![User files in the Gallery.](https://customerscanvas.com/docs/cc4/images/UsingImageGallery05.png) The **Edit** button allows for [editing the images](https://customerscanvas.com/docs/cc4/image-editor.htm.md). Your users can edit both private and public images. All edited images are saved in **My files**. ## Uploading Files On the **My files** tab, there is the **Upload files** button allowing your users to upload their artwork. Customer's Canvas allows for uploading files in the JPEG, JPG, GIF, PNG, BMP, PDF, AI, SVG, TIFF, and PSD file formats. The public image collection supports the same file formats. The **Gallery** allows for uploading a number of images at the same time. If you only need to select your personal file and insert it into a placeholder or an image layer, you can enable the [auto-insertion mode](https://customerscanvas.com/docs/cc4/client-config.htm.md). In this mode, you can select and upload only one image at a time. After the image is uploaded, the **Gallery** closes and inserts the image into the placeholder. ### PDF You can upload both single PDF files and PDF files contained in [smart objects](https://customerscanvas.com/docs/cc4/using-smart-objects-in-psd-templates.htm.md). When you upload a multipage PDF file, it appears in the **Gallery** on a page-by-page basis. ### PSD You can upload PSD files as either a raster image or a set of PSD layers by using the **merged** or **design** mode correspondingly. By default, the **design** mode is enabled. When you upload PSD files as a set of layers, Customer's Canvas ignores layers that have the `` or `` markers and places the rest of layers in the center of the canvas, keeping their relative position. If a width or a height of PSD files is bigger than the canvas size, then the editor fits the layers to the canvas size. You define how to upload PSD files through the **actionMode** property for a single tab. ``` "GalleryDialog": { "tabs": [{ "name": "User", "type": "user", "actionMode": { "psd": "merged" }, ... }] } ``` To allow for uploading PSD files on the **My files** tab, add the PSD extension to the list of allowed extensions. ``` config: { widgets: { GalleryDialog: { allowedExtensions: ["jpg", "jpeg", "png", "bmp", "gif", "svg", "pdf", "psd"] } } } ``` ### SVG Customer's Canvas allows you to import SVG files. If you design such files in Adobe Illustrator, save them using the **Tiny** SVG profile with the **Preserve Illustrator Editing Capabilities** option disabled. In other SVG editors, assign styles as path attributes, not through CSS. You can import SVG as a vector image or a combination of shapes by using the **vector** or **shape** mode. In the latter case, when you add shapes to the canvas, Customer's Canvas combines paths, rectangles, ellipses, lines, text, and other vector shapes from this file into one shape element. If you specify the fill and stroke colors for one of the shapes in the SVG file, these colors will be applied to the combined shape. If a number of elements have the fill and stroke colors, then the combined shape takes colors of the first element. To avoid any confusion in combining the shapes, you can merge them (Make a compound path in Illustrator) and apply the desired fill, stroke, and opacity to the resulting path prior to uploading. When you upload SVG as a vector image, it represents an image element on the canvas. This is the default mode. You can define how to import SVG files through the **actionMode** property for a single tab. ``` "GalleryDialog": { "tabs": [{ "name": "User", "type": "user", "actionMode": { "svg": "shape" }, ... }] } ``` ## Customizing the Public Files Collection The public images folder contains all images, which are available for all users. By default, it is the `~\PublicGalleryFolder\` folder. The path is relative to the site root. This folder usually contains subfolders. Subfolders' names are used to name categories in the **Public files** tab in the **Gallery**. Exceptions are "special" categories: - The **root** category contains files located in the public images folder and only appears if you put some files in this folder. - The **all** category contains all files from the public images folder and its subfolders. The public images folder and aliases for the **root** and **all** categories can be set in `~/Configuration/AppSettings.config` as follows: ```xml ... ... ``` When you design a product and have a set of stock images prepared for such products, you may want to configure the **Gallery** on a per-product basis. In this case, set the **publicFolderName** property of the **GalleryDialog** object to a subfolder name that contains these stock images. You can do it in `clientConfig.json` or through the [IConfiguration](https://customerscanvas.com/docs/cc4/customerscanvas.baseeditor.configuration.ui.igallerydialogconfigparsed.htm.md) interface as follows: ``` config: { widgets: { GalleryDialog: { publicFolderName: "Flyers" } } } ``` This configuration hides all folders in **Public files** except for the **Flyers** folder. Also, you can configure gallery tabs through the **tabs** array. ## Configuring Gallery Tabs Alternatively to the old approach, when you need to specify the **defaultTab** and **publicFolderName** properties, you can use a more flexible way using the **tabs** array. In the latter case, the **defaultTab**, **socialNetworkAppIds**, **publicTabEnabled**, **publicFolderName**, and **userTabEnabled** properties of **GalleryDialog** are ignored if they are defined together with **tabs**. ### Specifying Tabs Let us look at how you can configure the **Gallery**. The following example defines the **tabs** array, which matches the tabs shown in the previous screenshot. ``` "GalleryDialog": { "defaultTabName": "Public", "tabs": [ { "name": "User", "type": "user", "translationKey": "GalleryDialog.TAB_USER", "canEdit": true, "canUpload": true }, { "name": "Public", "type": "public", "subFolderName": "", "translationKey": "GalleryDialog.TAB_PUBLIC", "canEdit": false }, { "name": "Facebook", "type": "facebook", "canEdit": true, "appKey": "123456789012345" }, { "name": "Instagram", "type": "instagram", "canEdit": true, "appKey": "123456789012345" } ] } ``` Now that you have defined the **tabs** array, you can specify the default gallery view through the **defaultTabName** property and a tab name. For **public** tabs, you can set up the **subFolderName** property, which allows you to show files only from this folder. For example, you can create a subfolder of `~\PublicGalleryFolder\`, say `Frames`, where you can store frame templates. Then, define the corresponding gallery tab. ``` { "name": "Frames", "type": "public", "subFolderName": "Frames", "translationKey": "GalleryDialog.TAB_FRAMES", "canEdit": false } ``` Also, you can set up the **Toolbox** so that the **Gallery** opens in a required mode. ### Setting Up Gallery Tabs in the Toolbox You can implement separate buttons to launch the private and public galleries from the **Toolbox**. ![The Gallery buttons in the Toolbox.](https://customerscanvas.com/docs/cc4/images/UsingImageGallery04.png) To configure the buttons this way, define the **Toolbox** object in the `clientConfig.json` file or through the [IConfiguration](https://customerscanvas.com/docs/cc4/customerscanvas.baseeditor.configuration.ui.itoolboxconfigparsed.ibutton.htm.md) interface as follows: ``` "Toolbox": { "buttons": [ "Text", { "translationKey": "Toolbox.IMAGE", "translationKeyTitle": "Toolbox.IMAGE", "iconClass": "cc-icon-add-image", "buttons": [ "Image", { "translationKey": "Toolbox.FACEBOOK", "translationKeyTitle": "Toolbox.FACEBOOK", "iconClass": "cc-icon-add-facebook", "action": "Image", "tabs": [ "Facebook" ] }, "Background" ] } ] } ``` Here, the **buttons** array is defined using both predefined and custom buttons. The **Image** and **Background** are predefined public gallery buttons. Their names correspond to the **action** properties. To add such a button to the menu, just list its name/action in the buttons array. You can find the list of predefined button actions in the [IFrame API Reference](https://customerscanvas.com/docs/cc4/customerscanvas.baseeditor.configuration.ui.itoolboxconfigparsed.htm.md). To implement a custom gallery button, you need to include its definition in two objects in `clientConfig.json`, in the **Toolbox.buttons** and **GalleryDialog.tabs** arrays, like **Facebook** is defined above. The **tabs** property in the **buttons** array refers to an element of **GalleryDialog.tabs** that has the corresponding **name**. ## Adding the Layouts Tab In the context of Customer's Canvas, a product layout is a PSD file containing texts, image placeholders, shapes, and other design elements. The web-to-print editor allows your users to change layouts at runtime. To rearrange design elements on the canvas, you can just open a PSD template in the **Gallery**. When changing layouts, Customer's Canvas moves only texts and image placeholders to new positions and removes other design elements from your product by default. Customer's Canvas changes layouts in the following way: 1. Saves the content of text elements and image placeholders of the current product page. 2. Removes design elements that are not prohibited from being deleted by markers. 3. Pastes elements of the new layout into the current product page. 4. Pastes the saved content into the new placeholders. First, Customer's Canvas changes the content of placeholders having the same layer names in the current page and in the new layout. After that, the rest of placeholders take content in a random order according to their type. If the old layout had more placeholders than the new layout, then extra placeholders are removed. The background and foreground layers, marked with `` or ``, remain unchanged. If you need to keep the position and content of design elements, apply the `` marker to them. Applying the `` marker to texts and image placeholders, you allow them to be removed if the new layout does not contain enough appropriate placeholders. To open layouts in the **Gallery**, you need to prepare PSD files, add them to a subfolder of the `~\PublicGalleryFolder\` folder, and define the corresponding tab in the `clientConfig.json` file. The following example configures the **Toolbox** and **GalleryDialog** objects so that they contain only **Layouts**. ``` { "widgets": { "Toolbox": { // Create the Layout button in the Toolbox. "buttons": [{ "translationKey": "Toolbox.LAYOUTS", "translationKeyTitle": "Toolbox.TITLE_LAYOUTS", "iconClass": "cc-icon-layout", // Set the Layout action to merge layouts. "action": "Layout", // Refer to the Gallery's tab. "tabs": [ "Layouts" ] }] }, "GalleryDialog": { "tabs": [{ "name": "Layouts", "type": "public", // Specify the subfolder containing the layout templates. "subFolderName": "VerticalLayouts", // Specify the caption and hint for the Layouts tab. "translationKey": "GalleryDialog.TAB_LAYOUTS", "translationKeyTitle": "GalleryDialog.TAB_LAYOUTS", // Handle PSD files as a set of layers. "actionMode": { "psd": "design" }, // Specify the appearance of categories. "categoriesEnabled": false, // Specify whether the Edit button is available. "canEdit": false }] } } } ``` This **Layouts** tab shows only PSD files from the **VerticalLayouts** public subfolder. ## Adding the Background Tab You can set up the **Gallery** so that it displays backgrounds for user products on a separate tab. This tab may contain both images and the Color picker. The following example configures the **Toolbox** and **GalleryDialog** objects to display backgrounds. ``` { "widgets": { "Toolbox": { // Create the Background button in the Toolbox. "buttons": [{ "translationKey": "Toolbox.CHANGE_BACKGROUND", "translationKeyTitle": "Toolbox.CHANGE_BACKGROUND", "iconClass": "cc-icon-add-image", // Set the Background action to change background images or colors. "action": "Background", // Set the default tab shown when the Gallery opens. "defaultTabName": "Background", // Define two tabs in the Gallery for the Background mode. "tabs": [ "User", "Background" ] }] }, "GalleryDialog": { // Enable the Color picker. "backgroundColorPickerEnabled": true, // Enable the button for applying a background to all product pages. "insertToAllButtonEnabled": true, "tabs": [{ "name": "Background", "type": "public", // Specify the subfolder where you store images for backgrounds. "subFolderName": "Backgrounds", // Specify the caption and hint for the Background tab. "translationKey": "GalleryDialog.TAB_BACKGROUND", "translationKeyTitle": "GalleryDialog.TAB_BACKGROUND", // Specify the appearance of categories. "categoriesEnabled": true, // Specify whether the Edit button is available. "canEdit": false, "canUpload": false }] } } } ``` Here, the **backgroundColorPickerEnabled** property enables the Color picker for selecting plain backgrounds. When this property is `true`, the **Colors** category appears on gallery tabs. The **insertToAllButtonEnabled** property enables the **Insert to all** button allowing your users to apply a background to all product pages at once. To customize the icon of the **Background** button and gallery tabs available for users when they select backgrounds, the **Toolbox** object contains such a detailed definition. Generally, you can just add the predefined **Background** action to **Toolbox** to enable this button. The previous example results in the following gallery configuration. ![The Background gallery tab.](https://customerscanvas.com/docs/cc4/images/UsingImageGallery06.png) ## See Also ### Manual - [Integration with Facebook and Instagram](https://customerscanvas.com/docs/cc4/integration-with-facebook-and-instagram.htm.md) - [Simple and Advanced Web-to-Print Editor Modes](https://customerscanvas.com/docs/cc4/simple-and-advanced-designer-modes.htm.md) - [The Image Editor](https://customerscanvas.com/docs/cc4/image-editor.htm.md) - [The Asset Manager](https://customerscanvas.com/docs/cc4/asset-manager.htm.md) ### IFrame API Reference - [IGalleryDialogConfig](https://customerscanvas.com/docs/cc4/customerscanvas.baseeditor.configuration.ui.igallerydialogconfigparsed.htm.md) - [IToolboxConfig](https://customerscanvas.com/docs/cc4/customerscanvas.baseeditor.configuration.ui.itoolboxconfigparsed.htm.md)