Rule Editor

A content object's rule is an expression that calculates the object's value for each recipient — for example, a rule that returns "Mr." for male recipients and "Ms." for female ones, or a rule that builds a personalized greeting from a recipient's first name. The rule editor is the dialog where you create and edit these expressions, either by writing them directly as QLingo, or by building them visually.

To open the rule editor, right-click a content object or variable in the Dynamic Content panel and select Edit Rule. The window title reflects what you are editing — for example, Edit Content Object <name>, Edit Variable <name> or Edit Audience <name>.

Modes

The Mode dropdown at the top of the rule editor controls how the rule is presented:

  • Code Editor: The plain QLingo text editor.

  • Rule Builder: The visual, element-based editor. This is the default for most content objects.

  • Rule Designer: A specialized editor, available only for Table, Multi-Page PDF Table, Personalized Image (uImage), Style and Text with Style content objects, and for audience-linked content objects and variables. When you open the rule editor for one of these, it starts in Rule Designer automatically. For a Style or Text with Style content object, Rule Designer is available only while the rule is a single style call (see Define a rule for a Style or Text with Style content object).

Code Editor and Rule Builder stay in sync with each other: a change made in one shows in the other as soon as you switch. When Rule Designer is available, it stays in sync with both.

Rule Builder elements

In Rule Builder, the rule appears as a sequence of clickable elements. Each element is either:

  • a value — a constant, an input data field, a variable, or a function call;

  • an operator

  • a control-flow keyword such as If, Then, Else and Switch.

To modify the rule, click an element and pick an action from its menu: replace the element with a different value, extend it with an operator, group it in parentheses, or remove it with Delete, Remove operator or Remove function. Deleting a value that is one side of an operator removes the operator as well and keeps the other value. The sections that follow describe these actions in detail.

If part of the rule cannot be parsed, for example a parenthesis was left unclosed in Code Editor, Rule Builder shows that part as an error element with the parser's message. The error element behaves like any other value: click it and pick a replacement from its menu to repair the rule.

Choose the kind of rule

The first element of every rule sets the kind of rule. To change the rule kind, click the first element and select one of the following:

  • Value definition: A plain expression that evaluates to a single value. This is the default for a new rule.

  • Conditional check: An If <condition> Then <value> Else <value> structure. To add more branches, click the Else element and select Else If. To remove a branch, click its Else or Else If element and select Remove.

  • Multiple cases: A switch with one or more cases, optionally followed by a default. To add a case, click any existing case and select Add case before or Add case after. To add the default branch, click any case and select Add default. To remove a case, click it and select Remove.

Note: A database query is not one of these choices — a query can only be written in Code Editor. An existing query rule still opens in Rule Builder, which shows the query but cannot edit it; to change it, switch the Mode dropdown to Code Editor.

You can also nest one kind of rule inside another — for example, place a switch inside one of the branches of a conditional check — by opening the menu of an inner element and selecting Conditional > If or Conditional > Switch.

Insert building blocks

Each element's menu groups the available building blocks into the following submenus:

  • Input Data Fields and Variables: Every input data field or variable defined in the plan. When the list contains more than 30 entries, the submenu shows the first 30 followed by More, which opens a selector with the full list.

  • Constants: Text, Number, Boolean (True), Boolean (False), Date, Empty, Skip. Skip inserts the Skip operator, which skips the current record during job processing (see Skip operator). When the content object can return a file or graphic (such as a graphic content object), the submenu also includes Browse For File, which inserts a string constant with a file path you pick from disk.

  • Conditional: Wrap the current expression in an If or Switch structure.

  • Numeric Functions, String Functions, Date Functions, Conversion Functions: All the QLingo functions, grouped by purpose. For details of each function, see QLingo Language.

  • Custom Functions: JavaScript or QLingo functions defined in the linked plan. Each function appears with its real name and the correct number and types of parameters. This submenu is hidden when the plan defines no custom functions.

    Style and TextWithStyle are reserved for the built-in style functions. If the linked plan defines a custom function with either name, rename it in uPlan: the rule editor always writes calls to the built-in function.

  • Style and TextWithStyle: Insert a call to the matching style function. Style is offered only for a Style content object, and TextWithStyle only for a Text with Style content object.

    When you click one of the style parameters of such a call, the menu also offers Character Styles and Object Styles (each ending with an option to create a new style), Font Family, Font Style and Fill Color (the document's swatches, plus Custom for a CMYK value). Type the font size directly. The parameters must stay in their fixed order: base style, font family, font style, font size, fill color.

  • Graphic Functions: Barcode, rectangle and asset functions. Available when the content object can return a graphic value.

  • Personalized Image (uImage): Inserts a call to uImage() and switches the rule editor to Rule Designer mode for that call. Available when the content object can return a graphic value.

  • PDF asset pages as table (PDFAssetPagesTable): Inserts a call to PDFAssetPagesTable, which turns the pages of a PDF asset into the rows of a table. Available only for Table and Multi-Page PDF Table content objects, since the function returns a table.

    If the call becomes the whole rule, the rule editor switches to Rule Designer, where you pick the PDF file. Inserted inside a larger expression, it stays in Rule Builder, so you can build an elaborate rule around it, for example, an If that picks a different PDF per recipient.

  • Production environment value (GetEnv): The recognized production environment keys, as detailed in GetEnv Functions.

  • Get touchpoint data value (GetTouchpointData): Inserts a call to GetTouchpointData, which reads a value collected by a Circle touchpoint.

  • Special Characters: End of paragraph (\r), Forced line break (\n), Tab (\t).

Extend the expression

To add an operator or another value next to an existing element, click the element and select Extend Right or Extend Left. Both submenus offer the operators that are valid for the element's data type and for its position in the expression:

  • Arithmetic operators: String concatenation, Addition, Subtraction, Multiplication, Division, Division without remainder, Modulo - The remainder of a division.

  • Comparison operators: Equal to, Not equal to, Greater than or equal to, Less than or equal to, Greater than, Less than.

  • Logical operators: Logical AND, Logical OR.

For example, to follow a recipient's first name with a greeting, click the First Name element and select Extend Right > String concatenation. Then click the new empty element, select Constants > Text, and type the greeting.

Extend Left also offers Minus and Logical NOT, which act on a single element rather than connecting two. Minus negates a number (for example, turns [Age] into -[Age]); Logical NOT inverts a True/False value.

Edit function parameters

In a function call, a comma element separates the parameters. To add a parameter, click an existing parameter and select Extend Right (or Extend Left) > Function parameters separator (,). To remove a parameter, click the comma element before it and select Remove parameter.

Group with parentheses

To control the order in which arithmetic or logical operators are evaluated, click any element and select Wrap in Parentheses. The element is enclosed in a parenthesized group. To remove the grouping, click one of the parenthesis elements and select Remove Parentheses.

Build a rule

The procedure below uses the techniques described in the preceding sections to build a rule that returns the descriptive text "Child", "Teen" or "Adult" based on the value of an Age input data field. The completed expression reads:

If Age < 13 Then "Child" Else If Age < 20 Then "Teen" Else "Adult"

The procedure assumes a newly created text content object (for example, AgeGroup) that does not yet have a rule. When you open the rule editor for such a content object, the rule starts as a single empty string value next to the Value= label.

To build the example rule:

  1. In the Dynamic Content panel, right-click the AgeGroup content object and select Edit Rule.

  2. Click the Value= element and select Conditional check.

    The rule now has the structure of an if-then-else expression: an empty condition, an empty Then value, and an empty Else value.

  3. Define the first condition (Age < 13):

    • Click the empty condition element and select Input Data Fields > Age.

    • Click the Age element and select Extend Right > Less than (<).

    • Click the newly created Type element (T: / #: / D:), select Constants > Number, and type 13 in the inline edit box.

  4. Click the empty Then value, select Constants > Text, and type Child in the inline edit box.

  5. Click the Else element and select Else If.

    The Else branch now contains a second condition and value pair, followed by a new Else.

  6. Define the second condition and value (Age < 20 Then "Teen") by repeating steps 3 and 4 in the new branch, using 20 as the number and Teen as the string.

  7. Click the empty Else element, select Constants > Text, and type Adult.

  8. Click OK to save the rule.

The completed rule looks like this in Rule Builder:

Define a rule for a table content object

For a Table content object, the rule editor opens in a specialized editor (the Rule Designer) that lets you map a column in an additional data source to a column in the document's main data source.

Where that additional data source comes from depends on whether the document is connected to a server:

  • Local document: Data Source holds the path to a file on your computer, which you pick with Browse.

  • Document connected to uProduce or Circle: Data Source is a dropdown of the data sources already in the campaign, and the button beside it is New rather than Browse. The Table, Table Field and Equal To lists are read from the server.

Note: An existing table rule that points at a file on your computer keeps the path and the Browse button even on a connected document.

To define a table content object rule:

  1. In the New Content Object dialog, name the content object, set its Type to Table, and click OK.

    The rule editor opens straight away in Rule Designer mode.

  2. Select the additional data source:

    • On a local document, click Browse next to Data Source and select the file.

    • On a connected document, select one of the campaign's data sources from the Data Source dropdown. To add one that is not there yet, click New, select a file in the Upload Data Source to Server dialog and click OK. The file is uploaded to the campaign, added to the dropdown and selected. Uploading it under the name of an existing data source replaces that data source.

      Note: The upload happens as soon as you click OK in the Upload Data Source to Server dialog. Canceling the rule editor afterwards does not remove the data source from the campaign.

  3. From Table, select the table to use (when the data source contains more than one). For a CSV or other delimited text file on your computer, the Table dropdown is replaced by a Separator dropdown, where you select Comma (,), Tab or Semicolon (;), or type a different separator.

  4. From Table Field, select the column in the chosen table that uniquely identifies each recipient.

  5. From Equal To, select the matching column in the document's main data source.

  6. Click OK.

    The content object is created at this point, and not before. OK is refused while any of the fields above is still empty, and Cancel leaves no content object behind.

Define a rule for a Multi-Page PDF Table content object

For a Multi-Page PDF Table content object, the rule editor opens in Rule Designer mode with a dedicated panel: a PDF File field (with Browse) where you select the PDF that supplies the table's pages.

As with a Table content object, the content object is created only when you click OK, and Cancel leaves nothing behind. To point the rule at a variable instead of a fixed file, switch to Code Editor.

For the full procedure, see Tagging with a Multi-Page PDF Table Content Object.

Define a rule for a Personalized Image (uImage) content object

When a content object's rule is a uImage call, the Rule Editor opens in Rule Designer mode with a layout dedicated to uImage: a Package field, a Tag Mappings tree, a File Name area, a Format dropdown, and an Advanced button for the output folder and format options.

How you select the package depends on whether the document is connected to a server:

  • Local document: Package holds the path to a uImage document package (*.dpkg) on your computer, which you pick with Browse.

    Browse also accepts a standalone Photoshop (*.psd) template. Selecting one replaces the rule with a call based on that file (see uImage Functions) and switches the rule editor to Rule Builder, since Rule Designer handles only document packages. The template's tags are added to the call, each mapped to the input data field or variable of the same name, if there is one.

  • Document connected to uProduce: Package is a dropdown of the uImage template packages already in the campaign, and the button beside it is New rather than Browse. To add a package that is not there yet, click New and select the package file. The package is uploaded to the campaign, added to the dropdown and selected. If the campaign already holds a package with the same name, you are asked whether to replace it.

    Note: The upload happens as soon as you select the file. Canceling the rule editor afterwards does not remove the package from the campaign.

    If the campaign's packages cannot be read, the status line at the bottom of the rule editor shows The campaign's template packages could not be read. Try again later. If you select a package that does not contain a uImage template, the rule keeps its current package and the status line asks you to choose another one.

Note: The Advanced button is available for regular packages. It is hidden for Image Font and Separated Letters packages, whose advanced output settings are not available, and disabled until a package is selected.

OK is refused when the uImage rule would fail in production — for example, when no tag is passed to uImage, or a tag name has no value. The reason appears in the status line, and the rule editor stays open so you can fix the rule.

For the full procedure and the Advanced uImage Settings, see Defining a uImage Content Object.

Define a rule for a Style or Text with Style content object

The rule of a Style content object is a call to the Style function, which names an InDesign style and, optionally, font and color overrides. The rule of a Text with Style content object is a call to the TextWithStyle function, which carries both the text and the style it is set in (see Style Functions). For example:

TextWithStyle("Gold member", "Title", "Arial", "Bold", "14", "Red")

When the rule is a single call, the rule editor opens in Rule Designer with one row per field:

  • Text: The text to show (Text with Style only). The text is a single row of elements, which can combine fixed text, input data fields and variables, joined on one line, as in a uImage tag value. Click an element and pick an action from its menu, as in Rule Builder: for example, replace it with an input data field or a variable, or join more text to it. If and Switch are not offered here: if the text needs a condition, edit the rule in Rule Builder.

  • Style: Whether the style is a Character Style or an Object Style. In a Text with Style content object, the style is always a Character Style, because an object style cannot be applied to text, and this row cannot be changed.

  • Character Style or Object Style: The InDesign style to apply, from the document's styles. [Default] applies no style, so the text keeps the formatting it has in the document.

  • Font Family, Font Style, Font Size, Fill Color: Overrides applied on top of the style. (No Override) keeps the style's own value. Font Style lists only the styles of the selected font family. Font Size is in points; select a size or type one. Fill Color lists the document's swatches.

When the style is not set yet, for example in a new Text with Style content object, the rows show InDesign's default font, size 12 and the Black swatch as a starting point. These values are written to the rule only if you change one of the rows. If you click OK without changing anything, the rule keeps no overrides.

If the rule is more than a single call — for example, an If that picks a different style per recipient, or a text that holds an If or a Switch — Rule Designer is not available; edit the rule in Rule Builder or Code Editor. In a Text with Style content object, each branch must be a complete TextWithStyle call, and the rule editor wraps each branch in one for you. OK is refused if a TextWithStyle call is only part of a branch's value, for example when it is joined to other text.

The style is applied where InDesign places the text, such as print, proof and preview. HTML, email and flat data (CSVX) output receive the value as is, including its style information. Text with Style is not supported in uCreate XLIM documents: the XLIM preflight reports it as an unsupported dynamic style (see Style Functions).

If the content object's style is calculated in a way that cannot be shown as separate rows (typically a rule written in uPlan), an Edit Style button appears at the top right of the rule editor. Click it to edit the style in a second rule editor.

Define a rule for an audience-linked content object or variable

If a content object or variable has its Link to Audience option set, the rule editor opens in Rule Designer with one row per segment of the linked audience plus a default row:

Define an expression for each segment using the same building blocks described earlier in this topic. At runtime, each recipient receives the value from the segment they belong to, or the default value if they don't match any segment. For more information, see Creating an Audience.

You can also edit the segment values in Code Editor or Rule Builder. There, the rule appears as a single switch on the audience, with one case per segment, in the audience's order, followed by the default. For example:

switch(@{Audience.Loyalty})
{
    case "Gold":
        "Thanks for 10 years"
    case "Silver":
        null
    default:
        "Welcome"
}

A segment with no value shows as null. If you leave it as null, recipients in that segment receive the default value.

You can change the value of each case, including nesting another rule, such as a conditional check or a switch, inside it. The switch on the audience and the case names must stay as they are: in Rule Builder, these elements are locked, and clicking them shows a message to that effect.

When you click OK, or switch from Code Editor or Rule Builder to another mode, the rule editor checks that the rule is still a switch on the audience, with exactly one case for each segment and one default. If it is not, the rule is not accepted, and a message at the bottom of the rule editor explains why. Case names are not case-sensitive.

To update the values of all objects linked to an audience in one place, see Maintaining Audiences.

For a Text with Style content object linked to an audience, each segment's value and the default value are separate TextWithStyle calls, so each segment can have its own text and style.

Edit the rule as QLingo

If you prefer to read or write the rule directly as QLingo text, open the Mode dropdown at the top of the rule editor and select Code Editor. Type the expression directly, or paste an expression copied from elsewhere.

If the QLingo cannot be parsed, Rule Builder shows the part it could not read as an error element, which you can click and replace — see Rule Builder elements.

The Code Editor has its own visual option:

  • Wrap lines in Code Editor: When checked, long QLingo expressions wrap onto multiple lines.

To control how long expressions look in the visual builder, use Visual Configurations (see below).

Customize the rule editor appearance

You can customize how elements are drawn in Rule Builder and Rule Designer. In Rule Builder mode, click Visual Configurations at the bottom of the rule editor to open the Visual Configurations dialog.

The dialog includes a Preview at the bottom that shows the effect of every change before applying.

Presets

The Preset dropdown applies a complete set of settings in one step:

  • Default: The standard look.

  • Flat, Light Grey, Grey, Dark Grey: Increasingly dark rectangular elements.

  • Rounded: Grey rounded elements with a blue hover.

  • Rounded-White: Dark-grey rounded elements with a white hover.

  • Custom: Set automatically when you change any individual setting.

Selecting a preset overwrites every setting in the dialog. To revert manual changes, click Reset to Default.

To share a configuration with other designers:

  • Save writes the current configuration to a file.

  • Load reads a previously saved configuration file and applies it.

Element Border (clickable widgets)

The border around each clickable element. For each edge (Top, Right, Bottom, Left), set the Color (six-digit hexadecimal number under the Color (#RRGGBB) column, for example #FFFFFF) and the Width in pixels (under the Width/Use column).

To set all four edges together, use the chain toggle between the Color (#RRGGBB) and Width/Use columns:

  • Turn the chain on to link the edges. The Top edge's color and width are copied to the other three edges immediately, and any later edit to one edge is mirrored to the others as you type.

  • Turn the chain off to set each edge independently.

For the Element Border, the chain is off by default. The chain state is saved per user and restored the next time you open the dialog.

Element background: Below the four edges, set the fill Color for elements. The background is applied only when the checkbox in the Width/Use column is selected.

Hover Border (mouse over)

The border around the element currently under the mouse pointer. Set its Color and Width.

Edit Box Border (text inputs)

The border around the editable field inside string, number and date elements. Configured per edge in the same way as the Element Border, including the chain toggle — for the Edit Box Border, the chain is on by default.

Layout

  • Min text box width: Minimum width of editable fields inside elements, in pixels. The field grows automatically as you type a longer value.

  • Padding: Horizontal padding inside the element, in pixels.

  • Element gap: Horizontal gap between adjacent elements, in pixels.

  • Text alignment: Alignment of the text inside elements: Left, Center or Right.

  • Corner radius: Pixel radius of the element's rounded corners. Set to 0 for sharp corners.

  • Wrap long expressions onto multiple lines: When checked, a function call with more than two parameters wraps in Rule Builder so that each parameter appears on its own indented row. (If/Then/Else and Switch structures always appear on multiple rows, regardless of this setting.)

Visual Configurations affects Rule Builder and the element-based parts of Rule Designer. The settings are saved per user.

More topics

Examples of Content Object Rules

QLingo Language

Style Functions