Using the Image Gallery

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

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 popup menu. The layer's arrow popup menu.

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

The Gallery.

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.

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.

The Edit button allows for editing the images. 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, and PSD file formats.

When you upload a PDF file, it appears in the Gallery as rasterized PNG files, which represent single pages of that PDF file.

You can upload PSD files as either a raster image or a set of PSD layers. You define how PSD files are uploaded through the downloadPsdAsImage property of GalleryDialog. Set this property to false to add PSD layers to the canvas. To enable this feature globally, edit the ~\Configuration\clientConfig.json file. Also, you can enable or disable this feature for a single product through the IGalleryDialogConfig interface at runtime.

JavaScript
config: {
    widgets: {
        GalleryDialog: {
            downloadPsdAsImage: false
        }
    }
}

When you upload PSD files as a set of layers, Customer's Canvas ignores layers having the <BG> or <FG> 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.

By default, downloadPsdAsImage is true, so Customer's Canvas uploads PSD files as raster images.

To allow for uploading PSD files on the My files tab, add the PSD extension to the list of allowed extensions.

JavaScript
config: {
    widgets: {
        GalleryDialog: {
            allowedExtensions: ["jpeg", "gif", "png", "jpg", "bmp", "pdf", "psd"]
        }
    }
}

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 web.config as follows:

XML
<appSettings>
...
    <add key="PublicGalleryFolder" value="~/PublicGalleryFolder" />
    <add key="RootCategoryName" value="root" />
    <add key="AllCategoryName" value="all" />
...
</appSettings>

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 interface as follows:

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

JavaScript
"GalleryDialog": {
    "defaultTabName": "Public",
    "tabs": [
      {
          "name": "My Files",
          "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.

JavaScript
{
    "name": "Frames",
    "type": "public",
    "subFolderName": "Frames",
    "translationKey": "GalleryDialog.TAB_FRAMES",
    "canEdit": false
}

Also, you can set up the Left Toolbar so that the Gallery opens in a required mode right from this toolbar.

Setting Up Gallery Tabs in the Left Toolbar

You can implement separate buttons to launch the private and public galleries from the Left Toolbar.

The Gallery buttons in the Left Toolbar.

To configure the buttons this way, define the LeftToolbar object in the clientConfig.json file or through the IConfiguration interface as follows:

JavaScript
"LeftToolbar": {
    "buttons": [
        "Text",
        {
            "translationKey": "LeftToolbar.IMAGE",
            "translationKeyTitle": "LeftToolbar.IMAGE",
            "iconClass": "cc-icon-add-image",

            "buttons": [
                "Image",
                {
                    "translationKey": "LeftToolbar.FACEBOOK",
                    "translationKeyTitle": "LeftToolbar.FACEBOOK",
                    "iconClass": "cc-icon-add-facebook",
                    "action": "Image",
                    "tabs": [ "Facebook" ]
                },
                "Background"
            ]
        }
    ]
}

Here, the buttons array is defined using the 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. To implement a custom gallery button, you need to include its definition in two objects in clientConfig.json, in the LeftToolbar.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 <FG> or <BG>, remain unchanged. If you need to keep the position and content of design elements, apply the <ROLC_f> marker to them. Applying the <ROLC_t> 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 LeftToolbar and GalleryDialog objects so that they contain only Layouts.

clientConfig.json
{
    "widgets": {
        "LeftToolbar": {
            // Create the Layout button in the LeftToolbar.
            "buttons": [{
                "translationKey": "LeftToolbar.LAYOUTS",
                "translationKeyTitle": "LeftToolbar.TITLE_LAYOUTS",
                "iconClass": "cc-icon-layouts",
                // Set the Layout action to merge layouts.
                "action": "Layout",
                // Refer to the Gallery's tab.
                "tabs": [ "Layouts" ]
            }]
        },
        "GalleryDialog": {
            // Handle PSD files as a set of layers.
            "downloadPsdAsImage": false,
            "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",
                // 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 LeftToolbar and GalleryDialog objects to display backgrounds.

clientConfig.json
{
    "widgets": {
        "LeftToolbar": {
            // Create the Background button in the LeftToolbar.
            "buttons": [{
                "translationKey": "LeftToolbar.CHANGE_BACKGROUND",
                "translationKeyTitle": "LeftToolbar.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 LeftToolbar object contains such a detailed definition. Generally, you can just add the predefined Background action to LeftToolbar to enable this button.

The previous example results in the following gallery configuration.

The Background gallery tab.

See Also

Manual

IFrame API Reference