Variable Data Printing

Some products may require personalization of every printed copy, for example, when you are preparing letters and pre-addressed envelopes for mass mailings (so-called mail merge), creating wedding invitations, or printing business cards in a corporate style.

The most important benefit of variable data printing is a better connection to your customers, giving them the possibility to feel that you remember every customer personally. The mail merge, for example, makes a letter more personal and helps to increase the response rate and decrease the response time. The making of hundreds of similar personalized files manually would be time-consuming, and the technique of variable data printing allows for creating one template with placeholders and populating them from a certain data source for each personal copy.

Variable Data Printing Workflow

To personalize a print product by using Customer's Canvas, you need to implement the following steps:

  1. Design a template in either Photoshop or Customer's Canvas and save this template as a state file.
  2. Prepare a data sample from your database or CSV/XLS files.
  3. Render the hi-res outputs for your data sample items.

State files in Customer's Canvas maintain all information on the product, including images, user changes, fonts, colors, etc. They are created every time you call Editor.saveProduct to save a product, or Editor.finishProductDesign to render a hi-res output. You can move these files between folders of different users, rename them, or back them up. You can also copy state files to the \ProductTemplates\designs folder to use them as product definitions.

Customer's Canvas allows you to specify design elements as variable items by using their names or the isVariable flag. You can only set the isVariable flag for custom items being added from the Toolbox. To predefine item names, you can:

  • Enable the Variable item mode and mark design element as a variable in the Object Inspector.
  • Define corresponding layer names in Photoshop.
  • Add custom design elements with predefined names in the editor.

Allowing Users to Define Variable Fields

Your users can specify what design elements they need to personalize. To allow your users to mark design elements as variable, you can enable the Variable item mode in the clientConfig.json file. The following settings allow you to enable this mode.

json
{
    "variableItemsMaskSymbol": "%",
    "widgets": {
        "ObjectInspector": {
            "variableItemsEnabled": true
        }
    }
}

Here, variableItemsEnabled enables the variable data printing mode. In this mode, your users can click checkboxes in the Object Inspector to mark variable items.

Variable data printing. Variable item mode enabled.

Under the hood, Customer's Canvas encloses variable item names in variableItemsMaskSymbol. So, another way to specify fields as items to be personalized is to enclose their layer names in the mask symbol in Photoshop. By default, this symbol is "%".

Providing a Set of Variable Fields

Your users can add predefined design elements that need personalization from the Toolbox. Customer's Canvas allows you to provide a set of custom design elements for which you can specify a location, properties, and whether these elements require personalization or not.

The following example of the widgets section of clientConfig.json adds three custom buttons to the Toolbox: CardID, Logo, and SiteUrl.

json
{
    "widgets": {
        "Toolbox": {
            "buttons": [{
                "action": "CustomText",
                "iconClass": "cc-icon-add-text",
                "itemConfig": {
                    "name": "CardID",
                    "text": "1234  ABCD  5678",
                    "isVariable": true,
                    "textPermissions": {
                        "allowChangeText": false
                    }
                }
            },
            {  
                "action": "CustomImage",
                "iconClass": "cc-icon-add-image",
                "itemConfig": {
                    "name": "Logo",
                    "imageUrl": "http://example.com/logo.png",
                    "isVariable": true,  
                    "location": {
                        "originX": "left", "originY": "top",
                        "x": 100, "y": 300
                    }
                }
            },
            {
                "action": "CustomBarcode",
                "iconClass": "cc-icon-qr-code",
                "itemConfig": {
                    "barcodeContent": {
                        "barcodeFormat": "QrUrl",
                        "url": "example.com"
                    },
                    "name": "SiteUrl",
                    "isVariable": true,
                    "width": "100",
                    "location": {
                        "originX": "right", "originY": "bottom",
                        "x": 500, "y": 200
                    }
                }
            }]
        }
    }
}

After these predefined fields have been added to the canvas, your users can click checkboxes in the variable data printing mode to discard the isVariable property.

Retrieving a Variable Item List

When you don't know in advance which fields should be personalized, you need to retrieve their names from state files. You can do this on the client or server side by checking if their names are enclosed in variableItemsMaskSymbol. On the client side, you can also verify the isVariable property as follows:

JavaScript
CustomersCanvas.IframeApi.loadEditor(iframe, product)
    .then(function(e){
        editor = e;
    });

async function  getVariableItems() {
    var variableItems = await editor.eval(function () {
        var data = [];
        var product = spEditor.model.product;
        var items = product.getAllItems();
        items.forEach(item => {
            if (item instanceof CustomersCanvas.Model.ContentItem && item.isVariable) {
                data.push({ name: item.name, value: item.text});
            }
        });
        return data;
    });
    console.log(variableItems);
}

Rendering Personalized Designs with the Web API

Customer's Canvas provides a Web API to personalize products and render both proof images and hi-res outputs without loading the editor. To use this Web API, you need to pass new content and properties of variable items, a product definition, and the user identifier under which the links to proofs and hi-res outputs will be saved. You can also specify product themes and pass parameters of proof and hi-res files.

Pass new content and properties of variable items in itemsData. For example, you can specify text fields and images as follows:

JavaScript
itemsData = {
    "Name": {
        text: "John Wood",
        color: "rgb(255, 0, 0)"
    },
    "Logo": {
        image: "http://example.com/logo.svg",
        opacity: 0.8,
        size: {
            width: 100,
            height: 100
        }
    }
};

For more examples, you can refer to the Web API for Personalized Rendering topic.

Since this Web API allows you to render a number of products in a single request, you can pass a number of templates in the productDefinitions array.

The following example illustrates how you can generate a personalized product preview.

JavaScript
// Set your link to the HiRes controller. This Web API works through the HTTPS protocol.
const controllerURL = "https://localhost:44300/api/HiRes/GenerateHiRes";

// Personalize the Name text field.
async function personalize() {

    var inputData = {
        itemsData: {
            "Name": {
                text: "Cristopher Bennet"
            }
        },
        productDefinitions: ["3f0a09cf-ebdc-41d3-9cea-b6782e822ab2"],
        userId: "default"
    };

    // Make the request to personalize the product.
    $.ajax({
        url: controllerURL,
        type: "POST",
        headers: { "X-CustomersCanvasAPIKey": apiKey },
        dataType: "json",
        contentType: "application/json; charset=utf-8",
        data: JSON.stringify(inputData)
    }).
    fail(function (d) { console.log(d.statusText); }).
    done(function (d) {
        // List URLs that link to hi-res outputs.
        d.forEach(function (links) {
            console.log(links);
        });
    });
}

Personalization Samples

You can download a sample as a zip file and extract the vdp.html file into the root folder of Customer's Canvas and clientConfig.json into the \Configuration\ subfolder.

To make this sample work, in the \Configuration\AppSettings.config file, specify ApiSecurityKey with the same value as you use in the HTML file.

This sample allows you to open an empty product and add predefined text fields from the Toolbox. The personalization procedure includes the following steps:

  1. Saving the product to a state file.
  2. Getting a variable item list from this product.
  3. Personalizing variable items through the Web API.

As a result, you will get URLs that link to proof images.

You can also contact our support team to get a VDP demo package based on this Web API.

Generating Personalized Designs with the StateRenderer Tool

As an alternative to the Web API approach, Customer's Canvas provides the StateRender tool to personalize and render print products. This tool is in the ~\src\TestResources\StateRender source folder. You can build it from sources or contact our support team to get already built StateRender.exe. Also, you can use this source code in your e-commerce system. StateRender is a console utility accepting a state file, a JSON file with personal data, and an output folder for hi-resolution files. Such JSON files contain layer names and corresponding personalization data.

To use this tool, you can prepare templates using the following ways:

  1. Design a template in Photoshop, mark layers as variable placeholders, then open it in Customer's Canvas, and save this template in a state file.
  2. Design a template right in Customer's Canvas in the variable data printing mode and save this template.

Retrieving Variable Field Names

If you know in advance which fields should be personalized, you can skip this step. If your users define which fields are variable, then you should retrieve a list of all variable items. StateRender allows you to obtain such a list.

StateRender takes the following parameters.

StateRender.exe --stateFile=FileName.st [--replacements=FileName.json] [--outFolder=Folder]

Here, stateFile is the state file name. If you only pass this mandatory parameter, this console utility lists names of variable items. The replacements and outFolder parameters are optional. If you omit outFolder, then StateRender saves hi-res outputs and proof images in the \result\ subfolder.

When you run StateRender, the following output appears.

Output of the StateRender tool.

In this screenshot, StateRender found the City, Company, Name, and Photo variable elements. The first three elements are texts. The Photo field is an image. You can parse this list and use retrieved items to make a request to your database.

Passing Variable Data to the StateRenderer

To personalize your templates by using the StateRenderer tool, you should prepare a single JSON file for every entry in your database in the following format.

replacements.json
{
    "texts": { "%Name%": "John Doe", "%Company%": "Aurigma Inc.", "%City%": "Alexandria, VA" },
    "images": { "%Photo%": "photos/JohnDoe.png" }
}

Such a file may have two objects - texts and images - to replace elements of corresponding types. These objects contain the key-value pairs, where the values correspond to the layer names enclosed in the mask symbols. For images, the values are the file names relative to the utility executable file.

The Personalization Example

For example, let us personalize a conference badge. Design a template in Adobe Photoshop:

  1. Create a new template. On the File menu, click New.
  2. Add a background image. For example, drag it from Windows File Explorer. Add the <BG> marker to the name of the layer.
  3. Add a photo placeholder. Drag an image to the image layer.
  4. Add text layers. On the Tools panel, click Type Tool, click where you want to place text strings: City, Company, Name, and Conference.

The following image shows the resulting template that you may create.

The badge template in Photoshop.

This template does not contain any personal data yet. When you enable the variable data printing mode through variableItemsEnabled and open this template in Customer's Canvas, then the editor looks as follows:

Preparing a variable data template.

If you enable the variable data printing mode, check boxes appear in the Object Inspector for text and image elements. To mark a design element as variable, your users select the corresponding check box. They can do it through either the Object Inspector or Item Menu. In the latter case, the Make variable and Remove variable commands appear for texts and images.

Alternatively, you can mark design elements as variable items in Photoshop by enclosing their layer names in mask symbols, for example, %Name% or %Company%.

In this product, you need to vary names, company names, cities, and photos. Perform the following steps to render personalized badges:

  1. In Customer's Canvas, select check boxes for the Name, Company, City, and Photo objects.
  2. Save the product to generate a state file.
  3. Prepare a JSON file with replacements. You can obtain a list of variable data, running the following command.
    StateRender.exe --stateFile=StateFile.st
    
  4. Run StateRender with the state file and previous replacements as input parameters.
    StateRender.exe --stateFile=StateFile.st --replacements=replacements.json

Now that StateRender has personalized the product, you can find the following rendered badge in the output folder.

Variable data printing.

See Also

Manual

Downloads