Examples of Content Object Rules

This page collects sample rules for each kind of content object. Each example shows the completed QLingo expression as it appears in the rule editor's Code Editor mode, and explains the scenario behind it. The same rule is displayed visually as a sequence of clickable elements in Rule Builder. For step-by-step instructions on how to build a rule, see Rule Editor.

In the examples, |->[FieldName] is the QLingo notation for an input data field; @{varName} is the notation for a variable.

Text content object

Simple field reference

The most common rule for a text content object is a direct reference to a data field. The following rule, used by a FirstName content object, returns the value of the FirstName field for each recipient:

|->[FirstName]

Concatenation

The & operator joins strings. A Greeting content object that produces a salutation such as "Dear Jane Smith," uses:

"Dear " & |->[FirstName] & " " & |->[LastName] & ","

Conditional with concatenation

The data source includes fields such as FirstName, Age and Purchases (the number of times each recipient has shopped at the store). A Discount content object offers a 25% discount to shoppers over 20 who have shopped more than 10 times, and a generic message to everyone else:

if(AsNumber(|->[Age]) > 20 AND AsNumber(|->[Purchases]) > 10) "Dear " & |->[FirstName] & ", save 25% next time" else "Have a nice day"

The AsNumber() wrappers ensure numeric comparison even when the data source delivers the columns as strings (see the next example).

Data type conversion

Some data sources (Excel, CSV, plain text) do not let you declare a type for a column, so a numeric field may arrive as a string. To compare such a field to a number, convert it first with a conversion function:

if(AsNumber(|->[Age]) >= 18) "Adult" else "Minor"

For data sources that do support column types (such as a database table), set the right type at the source and the conversion is not strictly needed.

Switch (multiple cases)

When a value should be chosen from several discrete cases, a Switch is clearer than a chain of else if. The following rule returns a discount message based on the recipient's loyalty tier:

Switch (|->[Category])

{

Case "PLATINUM": "30% off your next order"

Case "GOLD": "20% off your next order"

Case "SILVER": "10% off your next order"

Default: "Thanks for shopping with us"

}

Text file content object

A text file content object's value is the name of a text file to use for the recipient. In this example, the rule picks a different file depending on the recipient's age:

if(AsNumber(|->[Age]) < 13) "Child.txt" else if(AsNumber(|->[Age]) < 20) "Teen.txt" else "Adult.txt"

Visibility content object

A visibility content object's rule evaluates to True or False, and the tagged design object is shown only when the rule is True. The following rule shows the section only for teens (ages 13–19):

AsNumber(|->[Age]) >= 13 AND AsNumber(|->[Age]) <= 19

Style content object

A style content object's value is the name of an InDesign character style or object style. The style name must match an existing InDesign style exactly. The following rule, used by a PriceStyle character style content object, highlights premium-tier customers in a different style:

if(|->[Category] == "PLATINUM") "PremiumPrice" else "RegularPrice"

For a fixed style, the rule is a single string constant, for example "HighlightRed".

Graphic content object

Asset name from a data field

A graphic content object's value is the name of an asset — a dynamic graphic file that changes per recipient. The example below personalizes a postcard for two recipients, Jane and Jerry. Each recipient sees a different school image.

The setup behind this is:

A data source column named School, with the school name of each recipient (for example, Engineering, Medicine, Law).
An assets folder containing an image named after each school (for example, Engineering.jpg, Medicine.jpg, Law.jpg).

uCreate Print recognizes the graphic file's format automatically, so the value does not need to include the file extension. The rule simply returns the value of the School column:

|->[School]

Personalized image (uImage)

A graphic content object can also point to a personalized image generated by uImage. The rule calls the uImage.uImage() function with a Photoshop document package (.dpkg) and one or more tag-name / tag-value pairs:

uImage.uImage("Certificate.dpkg", "", "", "JPG", "FullName", |->[FullName])

This generates a personalized certificate image per recipient, with the recipient's full name placed into the FullName tag of the template. See uImage Functions for the full signature and additional examples.

Tip: When the graphic content object's type is set to Personalized Image (uImage), the rule editor opens in Rule Designer with a layout dedicated to uImage settings — you do not have to type the call by hand. See Rule Editor.

Link content object

A link content object holds a URL — either a fixed address or one that is personalized per recipient — and is attached to text or to a design object so the reader can click through. Link content objects are active only when the document is produced in the interactive PDF format, and they are available only in connectivity mode.

A static link uses a string constant:

"https://www.example.com/welcome"

A personalized link concatenates a fixed base with a per-recipient value. When the document is linked to uProduce or Circle, the automatic XMPieRecipientKey content object is available as the primary recipient identifier and is referenced with ?:

"https://www.example.com/profile?id=" & AsString(?)

If the recipient key may contain characters that are not URL-safe, wrap it in CleanRecipientKey():

"https://www.example.com/profile?id=" & CleanRecipientKey(AsString(?))

For the full procedure of creating a personalized URL, see Creating a Personalized URL with an XMPieRecipientKey Automatic Content Object.

Table content object

A table content object pulls recipient information from a second data source, in addition to the data source the document is linked to. It addresses the need to include recipient information from multiple data sources in a single document.

The new data source and the linked data source must share a column that uniquely identifies each recipient, such as a social security number, passport number, driver's license number or email address.

In this example, the document is linked to a data source named Owners.txt, which holds each recipient's personal details. The goal is to associate the document with a second data source, Purchases.txt, which holds each recipient's stock purchases. Both data sources share a column called Owner ID. The table content object rule points to Purchases.txt and maps its Owner ID column to the matching Owner ID column in Owners.txt. The result, for each recipient, is a table where each row is one of that recipient's stock purchases.

The rule for a table content object is built in Rule Designer, which opens automatically when you open the rule editor for a table content object. In Rule Designer you set:

Data Source: The additional data source (for example, Purchases.txt).
Table Field: The column in the additional data source that uniquely identifies each recipient (for example, Owner ID).
is equal to Recipient Field: The matching column in the linked data source (for example, Owner ID).

For the full Rule Designer reference, see Rule Editor.

Multi-Page PDF Table content object

A Multi-Page PDF Table content object turns the pages of a PDF asset into table rows — one row per page — which can then be flowed into the document. The rule is a call to the PDFAssetPagesTable() function. When the PDF file name is fixed:

PDFAssetPagesTable("catalog.pdf")

When the PDF file name varies per recipient (for example, a campaign dial that lets the customer upload their own PDF):

PDFAssetPagesTable(|->[BrochureFile])

Each row in the resulting table is a page reference of the form filename.pdf:pageNumber. Combined with Auto Flow on a text frame, this places each page of the PDF on a separate page of the InDesign document. See Tagging a Design Object with a Multi-Page PDF Table Content Object for the full procedure.

Database query (any content object)

Any content object whose rule kind is Database query can pull its value from an external database. The query is written as a SQL statement followed by a semicolon, and the special placeholder ? refers to the current recipient's primary field (XMPieRecipientKey). The following rule looks up the account ID of the recipient in an Accounts table:

SELECT AccountId FROM Accounts WHERE CustomerId = ?;

A database query rule kind can be edited in Code Editor only.

Using a variable in a rule

A variable defined in the plan is referenced in a rule with the @{varName} notation. The following text content object rule prefixes the recipient's first name with a salutation that is itself a variable (so that the same salutation can be reused in many places without repeating its logic):

@{Salutation} & " " & |->[FirstName]

See Managing Variables for how to define a variable.