Contact us Blog

If-Then-Else Conditionals in Document Templates

Overview

Apsona's document templates support conditional directives (i.e., if-then-else), so that you can selectively include or exclude content in your document based on data conditions. For example, when creating a Terms and Conditions document, you might want to create different sets of terms based on whether your customer's credit rating. Or when creating a thank-you letter, you might want to include extra content or verbiage to recognize your top donors.

Here, we describe how to use this feature. If you are not already familiar with Apsona Document Merge, you can visit our pages about the document generation tool in general, and generating Word and PDF documents in particular.

An example

Below is a screen shot of a small fragment in a Word document, illustrating the essentials of this feature. In this example screen shot, we use four special merge fields, IF, ELSE IF, ELSE and ENDIF, to provide the directives. Each of these directives is a standard Word merge field, created via Insert - Quick parts - Field or via the more expedient button-and-macro shortcut. The code in the example looks for the template field DayNo, and if that field has a value 6, it produces the text "Saturday." If not, the code looks for the field Day, and if that field has value Sun, it produces the text "Sunday." Otherwise, it produces the text "a weekday."

How to create a conditional directive

You can view an example animation showing how to create these directives using Word.

Structure of the IF directive

The IF directive must be of the very specific form

IF templateField operator value

where templateField is a merge field name, operator is a comparison operator, and value is the value with which to compare the merge field. The templateField in the IF directive will appear among the mappable fields in step 2 of the merge action builder, so that you can map it to a data field in your data source.

Examples of IF directives

IF Amount > 500 Valid
IF Stage = "Closed Won" Valid
IF hasProject Valid: tests whether hasProject is true (if a checkbox field) or non-empty (if it is not a checkbox field)
IF Oppties:Amount:Sum > 0 Valid: tests whether the sublist named Oppties has its aggregation Sum field positive. (See the documentation about sublists for more information about aggregation fields.)
IF Opp Stage = "Closed Lost" Invalid: embedded space in template variable
IF partnerLevel = "Gold Invalid: missing closing quote
if count < 10 Invalid: IF is not in upper case

Special case: Testing for empty fields

When you want to test whether a string or text field is non-empty, it is better to use the construct «IF MY_FIELD», without the operator or value, rather than using «IF MY_FIELD != "" ». This is because of the way databases distinguish between null and empty values. Thus, for example, suppose you have in your document the construct below:
The field MY_FIELD is «IF MY_FIELD» not «ENDIF» empty.
If you then use this document with data that contains a value for MY_FIELD, the result would be
The field MY_FIELD is not empty.
but if the data has a null or empty value for MY_FIELD, the result would be
The field MY_FIELD is empty.
Thus the effect is to inject the word "not" exactly when needed.

Avoiding empty spaces

If you create an IF conditional without an ELSE part on a line by itself, it will produce empty space if the conditional fails. Below is an example to illustrate this point. The above screen shot shows a template with two variations, the first with an IF-ENDIF on a line by itself (that will produce an empty region), and the second with an ENDIF on the next line (which will not produce an empty region). Note also that the "No empty regions" template has the Billing Street field immediately following the ENDIF, rather than on a separate line, so as ensure that it does not contribute a line break. For comparison, below the result of expanding the template on some sample data. The key reason why it works this way is that a line break is really a special (albeit hidden) character. So in the second "No empty regions" structure, the line break is included between the IF and the ENDIF, and when the IF condition fails, the line break is "swallowed up" along with the content of the IF-ENDIF. By contrast, with the first "Shows empty regions" structure, the line break is outside the IF-ENDIF part, and so it will appear in the output even if the IF condition fails.

Constraints and notes