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 insert PSD layers on 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 only.
  • 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.

Configuring Gallery Tabs

Alternatively to the old approach, when you need to specify the defaultTab and publicFolderName properties, you can use a more flexible method 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

Customer's Canvas allows your users to change product layout at runtime. You can just open a PSD template from the Gallery to arrange your design elements on the canvas according to their position in the PSD template.

To open layouts in the Gallery, you need to prepare PSD templates, 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.
            {
                "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
            }]
        }
    }
}

See Also

Manual

IFrame API Reference