Showing content conditionally

One way to personalize content is to show or hide one or more elements depending on the value of a data field or runtime parameter. For example, a paragraph written for Canadian customers could be hidden when the recipient of the letter is not living in Canada, if that can be derived from the data.

Showing or hiding elements using the Conditional Content Script wizard

The Conditional Script Wizard helps you to show or hide an element – a paragraph, image or other HTML element - based on the value of one or more data fields and runtime parameters. For example, you could check whether the data field 'State' is 'Equal To' the value 'British Columbia' or 'Québec', to include a paragraph only for recipients in those states.

To open the Conditional Script wizard:

Select one or more elements, right-click and choose Make Conditional.
Alternatively, click the black triangle on the New button on the Scripts pane at the bottom left of the window, and click Conditional Content Script.

In the wizard, first make the following settings.

Rename the script so that it reflects what the script does.
Scripts can only have the same name when they are not in the same folder. (See Managing scripts.)
Type a Selector. The selector selects one or more pieces of text or elements from the template, so that the conditional content script can hide or show those pieces.
An ID (for example: #conditional-script) is best if you want to show or hide one element only.
Use a class selector (for example: .conditional) if the script should show or hide more than one element. See Using the Text Script Wizard for further explanation on selectors.

When you start the Conditional Script Wizard by right-clicking an element, the Selector field is pre-populated with the element's ID and class (or classes). If the element didn't have an ID or class, it gets a new ID (or class, in case multiple elements were selected) that is generated automatically.
If you'd want to change the selector later, you can do that after reopening the script (double-click the name of the script in the Scripts pane).
Set the Action: use the drop-down to select whether to Show or Hide the element when the condition below is true. When the condition evaluates to false, the opposite action is performed.

Once these settings have been made, the condition can be build.

The Add button adds a rule that evaluates a data field to a group.
To add either a group, or a rule that evaluates a runtime parameter, click the downward pointing arrow next to this button and select Group or Parameter Rule.

Creating a parameter rule is only possible if the template contains runtime parameters; see Runtime parameters.

The rule(s) apply at a Group level. There may be one rule or many rules at the same level, and there may be groups within groups, providing the ability to create quite complex nested logical structures.

Group

A group consists of one or more rules with a logic operator. Four logic choices are available at the Group level. These are:

All of the following.
This equates to the logical operator (... AND ...).
If all of the associated criteria are met, then this group resolves to TRUE.
Any of the following.
This equates to the logical operator (... OR ...).
If any of the associated criteria are met, then this group resolves to TRUE.
Not all of the following.
This equates to the logical operator (NOT(... AND ...)).
If any (but not all) of the associated criteria are met, then this group resolves to TRUE.
Not any of the following.
This equates to the logical operator (NOT (... OR ...)).
If none of the associated criteria are met, then this group resolves to TRUE.

The top level is always a group. A group can contain one or more Rules and/or Groups.

Rule

A single rule evaluates one data field or runtime parameter using a single operator or function and a value (the "operand").

To construct a rule:

Click the downward pointing arrow next to Field, then select the data field or runtime parameter that should be evaluated.
Select the operator. The downward pointing arrow expands the list of operators with which the data can be evaluated.
The options available will depend upon the Data Field or Parameter type (they are "type aware"), but most have at least "is equal to" and "is not equal to" as an option. For the complete list of options per data type see Conditional Content script dialog.
Enter the Value that should be used for the conditional check.
- Values (in Strings) are case sensitive by default; you can click the button next to the value to make them case insensitive.
- Dates should be entered in ISO standard notation (yyyy-mm-dd) (see ISO 8601). It is best to select the date using the date selection option.

It isn't possible to enter more than one value in one rule. Comparisons to multiple values can be made by combining rules in a group.
For example, an "after" and "before" rule combined in one "all of the following" group can be used to check whether a date falls between two dates.

To save the script, click Apply or OK.

The selected action will be performed if the joint groups and rules evaluate to true.
If, conversely, the condition evaluates to false, the opposite action will be performed.

To see the result, toggle to the Preview tab at the bottom of the workspace (or select View > Preview View on the menu).

If a condition cannot be made with the wizard - for example, one that compares a data field to a runtime parameter value - you can click Expand and edit the code of the script (see Writing your own scripts). But be careful: once the script has been altered, there is no going back to the wizard.

Showing or hiding several elements with one conditional script

To apply one conditional content script to several elements, a CSS class or HTML element needs to be used as the selector of the script. When you select multiple elements and create a new conditional content script following the actions described in Showing or hiding elements using the Conditional Content Script wizard, a CSS class will be applied automatically.

If you have created the script yourself, or if you want a script to apply to more elements later on, you have to do this manually.

Double-click the conditional script in the Scripts pane to reopen it.
Make sure that the selector is a CSS class (for example, .male) or an HTML element with a certain CSS class (for example, p.male). See Using the Text Script Wizard for further explanation on selectors.
Apply the same CSS class to all elements that should be shown or hidden under the condition that you have set in the conditional script. Click each element and type the class (without the preceding dot) in the Class field.

Showing or hiding a text selection

When you right-click on an element and make it conditional, the element as a whole will be made conditional. This happens even when you select a few words in a paragraph and right-click those words; the paragraph as a whole will be made conditional.
It is, however, possible to show or hide a part of a paragraph.

If the text that you want to show or hide is short, you could use the Selector and Text option in the Conditional Content wizard and copy the text into the Text field. This option uses the specified selector as a trigger for the script. The script applies to all instances of the text found within the specified selector.

Searching for text can be a lengthy operation, compared to searching for an element with an ID. If performance is an issue, of if the search text is long, a better alternative is to wrap the text in a span element first.

Select the part of the text that you want to make conditional.
Right-click the selected text and click Wrap in span.
Type an ID and/or a class. An ID is fine if this is the only thing that should be shown or hidden on a given condition. Use a class if there is more that should be shown or hidden on the same condition.
Start creating a conditional content script from the Scripts pane. Use the ID or class as the selector of the script. See Showing or hiding elements using the Conditional Content Script wizard.