Variable Data

Variable data are data from a database or data file that are used to personalize documents. Data fields can be inserted in the text directly. For example, if a person's last name can be found in your data, the field that holds the last name can be used in the text of a web page,letter, invoice or email. Scripts in PlanetPress Connect Designer are the basis of Variable Data Publishing and are used to personalize documents based on your data.

After loading - or creating - a Data Model (see Data Model pane), a data mapping configuration, ordata from a data file or database (see Loading data), you can add variable data fields to the contents of your template. You can do this via the drag-and-drop method, or using the Text Script Wizard.

Use the Text Script Wizard when there are empty fields in the data, and the value of a data field needs to be preceded or followed by a space, line break or text in the template. Otherwise, empty data fields will cause empty lines and superfluous white spaces to show up in the text. You should also use this method for blocks of data, such as address blocks, and when you want to format data differently, for example, when you want a number to be displayed as a currency.

You can use the drag-and-drop method for simple fields that do not need to be preceded or followed by a space, line break or text.

Web templates are personalized just like any other template. There are a few extra possibilities, though; see Using variable data on a Web page.

Inserting variable data directly (drag-and-drop)

An easy, quick and direct way to insert variable data in the content is via drag and drop:

Open the section you want to add the data field to.
Drag and drop a data field from the Data Model pane at the bottom right into the content of your template.
To select and insert multiple data fields at the same time, press Shift or Ctrl, whilst selecting fields in the Data Model pane.

What happens is that:

A placeholder for the value of the data field shows up in the text. It looks as follows: @FIELDNAME@.
A script appears in the Scripts pane at the bottom left.

The script replaces the placeholders in the content with the value of a data field in the current record.

Switch to the Preview tab at the bottom of the workspace to see the script in operation. The value of the corresponding data field in the first record appears instead of the placeholder, everywhere where the placeholder is found in the text. This value will be refreshed when you browse through the records in the Data Model pane.
When the output (the letter, email, etc.) is generated, the text script executes for each record in the record set, and each time it replaces the placeholders by the value of the field in the current record.

In the Scripts pane you can see that the script has a name and a selector.

The drag-and-drop method automatically generates a script that is named after the data field (see the first column of the Scripts pane).

The selector (in the second column in the Scripts pane) is what a script looks for in the template. By default the drag-and-drop method wraps the placeholder text in a Span. (Select the placeholder and switch to the Source tab to see the Span element.) The Span's class is used as selector.

When you drag the same field to the content again, a second placeholder appears in the text, but no new script is added. The existing script will find and replace all placeholders that match its selector.

Press the CTRL key while dragging to wrap the placeholder in an absolute positioned box (a div) at the cursor position. Each placeholder inside the box - there can be multiple if you drag multiple fields - is wrapped in a Span, and each Span gets its own class.
This method is particularly useful when the document mainly consists of a PDF used as the background image of a section (see Using a PDF file or other image as background).

Drag the data field directly to the Scripts pane to create a script without adding a placeholder to the template.

Connect versions older than 2020.2 used the placeholder text as the script's selector. Looking for text in a text is a less optimized operation and may impact output speeds in longer documents. For that reason placeholders are now by default wrapped in a Span and the class of that Span is used as the script's selector.
If you would like the drag-and-drop method to behave like it did in older Connect versions, you can change its behavior via the Preferences (Window > Preferences > Editing), or hold the ALT key while dragging to change its behavior on the fly.

For more tips to make a template generate output faster, see Optimizing scripts.

Using the Text Script Wizard

The Text Script Wizard can insert one or more data fields into your template, each with an optional prefix and suffix. It is recommended to use the Text Script Wizard for blocks of data, such as address blocks, and when data fields can be empty or need to be formatted differently.

Create a new text script and open the Text Script Wizard. There are two ways to do this:
- On the Scripts pane at the bottom left, click the black triangle on the New button and click New Text Script. A new script appears in the list. Double-click the new script to open it.
- Select a word in the content. Right-click the selection and on the shortcut menu, choose Text Script.
The Text Script Wizard appears.
Change the name of the script to make clear what it does.

Scripts can only have the same name when they are not in the same folder.
The selector states the text to be found in the template. The results can be replaced by the script.

Hover over the name of a script in the Scripts pane to highlight parts of the template that are affected by the script.
- Text, for example: @lastname@, or {sender}. The text doesn't have to have any special characters, but special characters do make it easier to recognize the text for yourself. In the Text Script Wizard, click Text and type the text to find.
  
  A script made with the Text Script Wizard for a block of data already runs faster than a series of individual scripts, because it only has one selector. However, searching for text can be a lengthy operation, compared to searching for an element with an ID. When speed matters, select one of the two remaining options: Selector or Selector and Text. See also: Testing scripts and Optimizing scripts.
- An HTML/CSS selector:
  - HTML elements, such as a paragraph. In the Text Script Wizard, click Selector and type the HTML tag without the angle brackets, for example: p.
  - HTML elements with a specific class. In the Text Script Wizard, click Selector and type the class name, including the preceding dot, for example: p.green for all paragraphs with the class 'green' or .green for all kinds of HTML elements that have the class 'green'. See Styling and formatting for an explanation about CSS (Cascading Style Sheets).
  - An HTML element with a specific ID. In the Script Wizard, click Selector and type the ID, including the preceding #, for example: #intro.
    
    Each ID should be unique. An ID can be used once in each section.
  - Etcetera. See https://www.w3schools.com/cssref/css_selectors.asp for more selectors and combinations of selectors.
- A selector and text. This is text inside an HTML element (or several HTML elements) with a specific HTML tag, class or ID. In the Text Script Wizard, click Selector and text and type the selector and the text in the respective fields.
Click the the downward pointing arrow in the first row in the column Field. Select a data field from the list that appears.
Add a Prefix and/or a Suffix. The prefix and suffix can contain text and/or HTML tags. If a field is empty, the prefix and suffix will be ignored, which means you can add line returns and static text, such as:
- with a Number field, Prefix: Your invoice (one space at the end), Suffix: is now ready to be viewed!
- with a field LastName, Suffix <br/> (which adds a line break)
- with a field State, Prefix: , (comma then space).
For a comma between fields, use the Prefix of the second field, if you don’t want a comma when the second field has no value.
The Wizard allows you to reformat the data (for example, apply uppercase, apply thousand separators to numbers, etc.). Click the column Format, click the downward pointing arrow and select one of the formats. For an explanation of the formats see Formatting variable data.
Add as many data fields as you need, following the same procedure.
Optionally, you can click Options to specify where and how the script inserts its results:
- As HTML. HTML elements in the results are processed and displayed as HTML elements. For instance,
  <b>this is bold</b>
  will be displayed as this is bold. This is the default setting.
- As text. This inserts the results as-is, meaning HTML tags and elements are displayed as text in the output. In this scenario, "<br>" shows up in the text and does not insert a line break.
- As the value of an attribute of an HTML element. The selector of the script should be an HTML element. Which attributes are available depends on the selected HTML element. If the script's selector is an image (<img> element) for example, and the attribute is
  src
  , the script will modify the image's source. The script's results should be a valid value for the chosen attribute.
  
  When checked, the option Convert fields to JSON string writes the results from the script into an attribute or text as a JSON string. This is useful for web contexts where a front-end script can read this value easily.
Close the Text Script Wizard and type the placeholder for the results of the script in the content of your template, or make sure that there is at least one element that matches the selector of the script.
Hover over the name of the script in the Scripts pane. In the workspace you will see which parts of the template are affected by the script. If the script produces an error, the error message will be displayed in a hint on the Scripts pane.

When one of the included data fields is empty, the respective line, including the prefix and suffix, is skipped. The result of the script will be shorter, causing the rest of the content to move up or down. If, in a Print context, you don't want the result of the script to be part of the text flow (for example, when a letter is going to be sent in an envelope with a window), put the placeholder for the script in a positioned box (see Boxes and How to position elements).

An example of how to create an address block using the Text Script Wizard is described in a how-to; see How to create an Address Block.
To use only part of a data field, or to split the data, you will have to write a script. For an example, see this How-to: How to split a string into elements.