Creating and Editing Templates in Customer's Canvas

In the previous sections, we paid much attention to what Customer's Canvas is and what its role is in web-to-print solutions, where it is embedded (refer to Integration with E-commerce Overview). This topic elaborates on another aspect - how to create and edit product templates in Customer's Canvas. This functionality is crucial because the purpose of Customer's Canvas is a customization of print products. Consequently, understanding how to work with templates is very important for a successful implementation of Customer's Canvas.

The Photoshop Templates section describes in detail how to use Adobe Photoshop to prepare templates. It can give an impression that this is the only way to create templates for Customer's Canvas - in Adobe Photoshop. Actually, this is not true: Customer's Canvas can be used as a template editor in itself.

You can integrate Customer's Canvas in an administrative panel, where products are customized, they link to templates, and price lists are specified.

The workflow of providing templates to users can be described by the following steps:

  1. A designer selects a product for which they want to create a template.
  2. They open the Customer's Canvas editor. The site initiates an empty product according to the selected product size.
  3. They create the template in the editor.
  4. The Customer's Canvas editor saves the template into a server file system. The e-commerce system saves a template's thumbnail in its database and publishes it on the site.

To understand how to work with Customer's Canvas templates, let us see what an internal file format is (so called state files).

State Files

A state file is a result of saving all objects loaded in the editor, i.e. its state. A state contains all information on the product, including images, user changes, fonts, colors, etc. State files are created every time you call Editor.saveProduct to save a product, or Editor.finishProductDesign to render a hi-res output. They always have unique names that look like aaaaaaaa-bbbb-cccc-xxxx-yyyyyyyyyyyy.st. You can move these files between folders of different users, rename them, or back them up.

Note

By default, the image data is embedded into the .st file as a Base64 string. It makes the state file self-contained - you can easily copy it to a backup drive, restore, or even move it to another Customer's Canvas instance. However, such files can become pretty large. To avoid this, you can enable a space-saving mode by setting the StateFileStorageEnabled to true in web.config. In this case, all images will be stored in the \UserDataFolder\StateFileCache\ folder and state files will have links to the files in this folder. As a trade-off, you will have to copy this cache folder during the backup procedures or migration to another Customer's Canvas instance.

By default, product states are saved in the \UserDataFolder\someUserId\states\ folder for every user. The UserDataFolder contains states and images for all your users. You can set another folder path in the web.config file. someUserId is set when you load the Customer's Canvas editor:

JavaScript
var iframe = document.getElementById("editorFrame");
CustomersCanvas.IframeApi.loadEditor(
    iframe, 
    {   // Specify the empty product size.
        surfaces: [{ width: 800, height: 600 }] 
    },
    {   // Set a user id.
        userId: 'someUserId'
    }
);

If you open the state folder, you will see a lot of state files. How do you pick the right one? To load a state, you should know its name (i.e. the state ID). You can get the state name when a Promise object returned by the Editor.saveProduct or Editor.finishProductDesign is resolved. The state ID, along with other information about the state, is passed to the successful resolution callback:

JavaScript
editor.finishProductDesign()
    .then(function (result) {
        ...
        // Save state identifier and user identifier.
        stateId = result.stateId;
        console.log("State is saved successfully. Its id is " + stateId);
        ...
    })
    .catch(function (error) {
        ...
    });
...
// Load a previously saved product.
CustomersCanvas.IframeApi.loadEditor(iframe, stateId, { userId: userId });

Find more examples in Handling Product Customization.

Customer's Canvas does not automatically clean up the state files. They are kept forever, until you delete these files manually. The only exception is when you enable the Demonstration mode. In this case, state files of anonymous users will be automatically removed when the session expires.

Master User

When your employees create templates, their state files are saved under their user folder and they are not available to other users. How do you make their work available to all users of your site?

To provide a template for all your users, the specified state file must be located in the master user folder. The master user is a special user whose resources, such as images or state files, are accessible for every user in your system. When a user sets a state file to load, Customer's Canvas first looks for the state in the state folder of this user, and if it cannot be found there, the master user folder is checked. Usually, the master's folder is ~\UserDataFolder\masteruser\states\, where masteruser is the MasterUserId value. This value is set in the web.config configuration file; see the Configuration Parameters topic for more information.

There are two ways how a state file can appear in the master's folder. Firstly, you can allow a designer to work under an arbitrary user ID in your system, and when the work is done, just move a state file to the master user folder manually. Another way is to set the MasterUserId as the value of the userId configuration parameter when loading the editor. In the latter case, when the designer saves a product, its state file is placed right into the master user folder. You can rename state files to make their names more human-readable.

Samples

Importing a PSD Template

Let us assume you have a file named stamp.psd. You should put it into the \ProductTemplates\designs\ folder, which contains all PSD templates, and use the following JavaScript:

JavaScript
CustomersCanvas.IframeApi.loadEditor(
    // An iframe where CustomersCanvas editor should be loaded.
    iframe,
    {   // Specify the PSD name here (without extension).
        surfaces: ['stamp']
    }, 
    {   // In the configuration specify the user ID, in our case, masteruser, to make our template public automatically.
        userId: 'masteruser'
    }
);

Loading a Rasterized Image as a Background

If you have an image, you can load it into the editor as a background. The image can be .png, .jpg, or a .jpeg file. For example, to load SummerPhoto.jpg, put it into the \ProductTemplates\designs\ folder and use the following JavaScript:

JavaScript
CustomersCanvas.IframeApi.loadEditor(
    // An iframe where CustomersCanvas editor should be loaded.
    iframe,
    {   // Specify the image name here (without extension).
        surfaces: ['SummerPhoto']
    }, 
    {   // In the configuration specify the user ID, in our case, masteruser, to make our template public automatically.
        userId: 'masteruser'
    }
);

Opening a Blank Product

Now, let us create a template for a 800x600 product from scratch:

JavaScript
CustomersCanvas.IframeApi.loadEditor(
    // An iframe where CustomersCanvas editor should be loaded.
    iframe,
    {   // Specify the empty product size.
        surfaces: [{width: 800, height: 600}]
    }, 
    {   // In the configuration specify the user ID, in our case, masteruser, to make our template public automatically.
        userId: 'masteruser'
    }
);

Saving the Product

Now, let us see how to save the product:

JavaScript
editor.finishProductDesign()
.then(function (result) {
    // Save state identifier and user identifier.
    stateId = result.stateId;
    userId = result.userId;
    console.log("User " + usedID + " successfully saved " + stateId + " product");
})

Loading a Template from a State File

JavaScript
CustomersCanvas.IframeApi.loadEditor(
    iframe, 
    // Specify a state file name to load a product.
    "ee9293bc-c887-433d-a5bd-454888f07a8a",
    {   // Set a user id.
        userId: 'someUserId'
    }
);

A complete code sample can be found on the Handling Product Customization page.

See Also

Manual

IFrame API Reference