We already introduced markers - text strings in a specific format added to layer names. Using these markers, you can restrict such actions as deleting and rotating objects, replacing a specific image, changing font settings and text, etc. All these restrictions help keep a design consistent after being personalized by end users. However, what if we want not only to restrict some actions, but to format user input as well? Here placeholders come into play. Image placeholders are discussed in the Image Placeholders topic. In this topic, we discuss in-string placeholders used to format a user input in text layers.
An in-string placeholder is a substring in a text element that is formatted in a special way (not a part of element names, like the markers). There are two use cases where placeholders are extremely helpful:
As it was said before, the in-string placeholders are specially formatted strings in text elements. Using them, you can control what portions of text are editable in layers, format user input to match a specific template, provide multi-value text elements, and populate multiple elements with the same text.
Customer's Canvas provides the following types of in-string placeholders:
A text layer can contain multiple types of in-string placeholders in any combination and represent plain or rich formatted text.
Your users can edit the content of in-string placeholders in the Object Inspector and in pop-up boxes. If a text element contains a number of in-string placeholders, they appear in a single pop-up box.
You can also populate placeholders programmatically through the Web API and userInfo.
Now that you have an idea of how in-string placeholders work, let us learn how to use them. This topic gives examples of Photoshop templates, though you can specify in-string placeholders in InDesign in the same way.
To demonstrate all ways of using in-string placeholders, let us create a business card template and add different types of placeholders to it.
Replaceable text is the simplest type of placeholders: you just enclose a part of the text with brackets, and the user can edit this text in an arbitrary way. The text in the brackets is a hint explaining what the text layer stands for, so it is better to make the text as informative as possible.
Business cards usually contain an owner's name, position, and email. The owner's name can contain any character, so let us make it fully editable. The hint for the name will be Your_Name
. The position element will contain the Position
fixed word and the editable part of the actual position name. The email element will consist of the editable alias and two fixed parts, E:
and @your_company_domain.com
.
Now, let us start creating a template for such a business card.
[#Your_Name]
text into the first layer, Position: [#Your_Position]
into the second one, and E: [#Email_Alias]@your_company_domain.com
into the third layer. Save the template. The result should look as follows:
As mentioned above, Customer's Canvas allows for populating several elements with the same value. To use this feature, put the same placeholder into multiple positions in a template. When the template is loaded, there will be only one field in the Object Inspector in the "Single" mode. Whatever the user types in this field, it is copied to the multiple locations in the template. To demonstrate this feature:
[#Your_Name]
into the first text layer and [#Your_Position]
into the second one. The placeholders should be exactly the same as we placed in the first template. Save the template.
Masked text placeholders have the following format: [#Mask_Name#Mask]
. The Mask_Name
part is a hint that is shown to a user, and the Mask
part is a text template. The following symbols are treated as special and are replaced by user input in masks:
a
is replaced with a character.9
is replaced with a number.*
is replaced with either a character or a number.One of the most popular use cases for masks is phone numbers. So, let us add phone and fax numbers to the business card.
T: [#Phone#999-999-9999]
text into the first layer; it is the phone number. Put F: [#Fax#999-999-9999]
into the second layer; it is the fax number. Save the template. The result should look as follows:
Note that when the template is loaded, the nines (9
) are replaced with underscores because 9
is a placeholder symbol. However, the hyphens (-
) remain unchanged because a hyphen is not a special symbol.
If you want to load some user info into masked in-string placeholders, a value in the userInfo
dictionary should be formatted according to the mask, otherwise, the value is not applied to the placeholder. For example, for the [#Phone#999-999-9999]
placeholder, the userInfo
dictionary should look like this: {"Phone": "123-456-7890"}
.
One more type of in-string placeholders supported by Customer's Canvas is the multi-value text placeholder. In the web-to-print designer, they are represented by drop-down lists. The format of multi-value text placeholders is [#Placeholder_Name|value1;value2;value3]
, where Placeholder_Name
is a hint that is displayed in the Object Inspector, and value1
, value2
, and value3
are possible options. You can add any number of options to a multi-value text placeholder. All options should be separated by a semicolon (;
).
Let us put the address element, having two addresses to choose from, into the business card.
[#Address|335 Cloverfield Blvd, Carlington NY 54321;336 Cloverfield Blvd,Carlington NY 54321]
. Save the template. The result should look as follows:
If a multi-value text placeholder is automatically populated, then the value that will populate the placeholder should be one of the values listed in the template. Otherwise, the value from the userInfo
dictionary is ignored. For example, for the [#HonorificForm|Mr.;Mrs.]
placeholder, the userInfo
dictionary should be either {"HonorificForm": "Mr."}
or {"HonorificForm": "Mrs."}
.
As an alternative to multi-value text placeholders, you can use multi-value elements defined through the <MVI>
marker. For more details, refer to the Setting up Fields with Predefined Values topic.
The Object Inspector supports two display modes of linked in-string placeholders: Single and Multiple. As an example, let us open a template containing the following layers.
Here, the content of text layers corresponds to their names. This template has three in-string placeholders. The first layer contains two of them, [#Company_Name]
and [#City_Name]
. Also, [#Company_Name]
is in the fourth layer.
In this mode, every in-string placeholder appears only once in the Object Inspector despite that you can use it several times on different pages of your product. They always appear at the top of the list of design elements. For the previous example, the Object Inspector looks as follows:
To enable this mode, set the inStringPlaceholderMode property of the Object Inspector to "Single" in clientConfig.json
.
In this mode, the Object Inspector keeps the same order of design elements as defined in Photoshop. Also, the Object Inspector displays an in-string placeholder as many times as it appears in a template. If a text layer contains several in-string placeholders or a text with an in-string placeholder, then they appear as a group of elements. In the Multiple mode, in-string placeholders display violation warnings, if any, and allow for changing the z-order. For the previous example, the Object Inspector looks as follows:
Customer's Canvas enables this mode by default.