TrophyCustomer's Canvas is honored with a 2020 InterTech Technology Award! Learn more 

How to Personalize Design Elements in Your Template

As we discussed earlier, when sending a request to preview or hires, we pass a data object containing commands for personalized layers. Such a command represents an object that has a type and other settings specifying how to personalize that layer.

Supported Design Elements

Earlier, we gave an example of commands corresponding to the image and text layer types. Now, let us list all available commands and their settings. You can personalize the following types:

  • text - to personalize text layers. This type is only applicable to text.
  • shape - to change colors of vector graphics. This type is only applicable to shapes.
  • image - to replace images in templates. You can apply this type to image layers and smart objects.
  • switch - to allow your users to select an element design from a number of options. In Photoshop, you can combine these options into a group, and then specify the name of the layer that you want to enable in the request. You can also personalize such a layer by passing the commands. This type is only applicable to layer groups.
  • psd - to insert another PSD file into a smart object. This can be useful to generate mockup previews. You can only apply this type to smart objects.
  • table - to generate a table based on a prototype in a smart object. You can apply this type to smart objects that contain a table prototype.

When configuring an element, first specify the type property.

You can specify colors in the following formats:

  • HEX - (#ffffff)
  • RGB - rgb(255, 0, 0)
  • RGBA - rgba(255, 0, 0, 0.6)
  • CMYK - cmyk(25, 12, 80, 22)

For CMYK, the channel values are specified as a percentage in the range [0, 100].

You can specify the visibility of such ordinary elements as text, images, and shapes as follows: visible ? (bool) = true

Here, we use the following notation to define the configuration parameters:

paramName ? (typeName)

  1. paramName - the parameter name.
  2. ? - marks the parameter as optional.
  3. (typeName) - the parameter type is in parentheses.
  4. =true - the default value, if any.

Now, let us describe what properties you can change to personalize templates.

Text

  • visible ? (bool) = true - enables this text element.
  • text ? (string) - the content of this text element.
  • fauxItalic ? (bool) - enables the faux italic style for this text.
  • fauxBold ? (bool) - enables the faux bold style for this text.
  • color ? (string) - the text color.
  • postScriptName ? (string) - the PostScriptName of the text font.
  • size ? (float) - the font size.
{
    "data": {
        "Team": {
            "type": "text",
            "text": "Washington Capitals",
            "color": "#ff0000",
            "postScriptName": "ArialMT",
            "size": "20"
        }
    }
}

Shape

  • visible ? (bool) = true - enables this shape.
  • color ? (string) - the shape color.
{
    "data": {
        "Rectangle": {
            "type": "shape",
            "color": "rgb(200, 200, 0)"
        }
    }
}

Image

  • visible ? (bool) = true - enables this image.
  • image (string) - the link to the image source, either a local link relative to ImagePath or a direct URL.
  • page ? (int) = 0 - for multi-page PDF files, specifies the number of a page to be inserted.
  • resizeMode (string) - the image resize mode, either fill or fit.
  • dpiX ? (int) = 300 - X-coordinate resolution, in dots per inch. This parameter applies only to PDF images.
  • dpiY ? (int) = 300 - Y-coordinate resolution, in dots per inch. This parameter applies only to PDF images.
  • transform ? (object) - an object defining transforms:
    1. rotate ? (number) = 0 - the image rotation angle, in degrees. You can only rotate PDF images at 90, 180, and 270 degrees.
    2. flip ? (string) = none - the flip mode, either none, horizontal, vertical, or both.
{
    "data": {
        "Logo": {
            "type": "image",
            "Image": "http://example.com/capitals.png",
            "resizeMode": "fit",
            "dpiX": 150,
            "dpiY": 150,
            "transform": {
                "flip": "horizontal"
            }
        }
    }
}

Switch

  • select (string) - the name of a visible layer in this group, the rest of the layers are hidden.
  • data ? (object) - the configuration of the visible layer.
{
    "data": {
        "text_group": {
            "type": "switch",
            "select": "city",
            "data": {
                "type": "text",
                "text": "Carlington",
                "color": "#000000"
            }
        }
    }
}

Psd

  • content (string) - the path to a PSD file relative to TemplatePath.
  • data ? (object) - the configuration of design elements.
{
    "data": {
        "Team 2\\Away Table": {
            "type": "psd",
            "content": "home-away-games.psd",
            "data": {
                "City": {
                    "type": "text",
                    "text": "Chicago"
                },
                "Week": {
                    "type": "text",
                    "text": "18"
                }
            }
        }
    }
}

Table

  • data (array<object>) - an array of rows. Rows contain key-value pairs representing table cells. The keys in the data array are layer names, whereas values are the cells' content - either text or links to images.
  • settings (object) - an object defining the table style:
    1. color (array<string>) - an array of text colors.
    2. backgroundColor (array<string>) - an array of background colors.
    3. fontSize (string) - the text font size, either a number in points or auto (which means the Dynamic Image automatically fits the font size).
    4. horizontalMargin (int) - the margin between columns (gutter), in pixels.
{
    "data": {
        "Team1": {
            "type": "table",
            "data": [
                { "Col1": "Sep 10", "Col2": "Atlanta", "Col3": "12:00p" },
                { "Col1": "Sep 17", "Col2": "@ Tampa Bay", "Col3": "12:00p" },
                { "Col1": "Sep 24", "Col2": "Pittsburgh", "Col3": "12:00p" },
                { "Col1": "Sep 28", "Col2": "@ Green Bay", "Col3": "7:25p" }
            ],
            "settings": {
                "color": [
                    "#ffffff",
                    "rgb(200, 200, 200)"
                ],
                "backgroundColor": [
                    "rgba(242, 97, 34, 0.7)",
                    "#f26122"
                ],
                "fontSize": "auto",
                "horizontalMargin": "60"
            }
        }
    }
}

Table Prototypes

Before you start working with tables, you need to design a table prototype. In Photoshop, such a prototype represents a smart object containing another PSD file with the table layout.

You can add both text and image layers to a prototype. When DI renders a table, it takes font settings, text alignment, and the position of cells from your prototype. It fills in the table row by row and sets the row height automatically.

Note that you can arrange a number of layers in a table prototype under each other. In this case, you can personalize headers. For example:

Table Prototype

Add this prototype as a smart object to another PSD file:

Table Prototype

To personalize this table, you can run the following sample:

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>The Dynamic Image</title>
    <script type="text/javascript" src="https://code.jquery.com/jquery-2.2.0.js">
    </script>

<script language="javascript">
var render = function() {

var config = {
    "TableProto": {
        "type": "table",
        "data": [
            { "Header Col1": "Description", "Header Col2": "Price" },
            { "Col1": "15 inch wheel", "Col2": "$200" },
            { "Col1": "16 inch wheel", "Col2": "$275" },
            { "Col1": "16 inch wheel", "Col2": "$350"}
        ],
        "settings": {
            "color": ["#ff0000", "#0000ff" ],
            "backgroundColor": ["rgba(255,255,255, 100)", "rgba(200,200,200, 100)" ],
            "fontSize": "auto",
            "horizontalMargin": "10"
        }
    }
};

var data = { template: "template.psd", data: config };

$.ajax({
    url: "http://localhost:84/api/hires",
    type: "POST",
    contentType: 'application/json; charset=utf-8',
    dataType: 'json',
    data: JSON.stringify(data),
    success: function(d) { 
        console.log(d);
    },
    error: function(d) { 
        console.error(d.responseText);
    }
});
}
</script>
</head>

<body>
    <h3>The Dynamic Image</h3>
    <input type="button" value="Personalize" onclick="render()" />
</body>
</html>