OverviewApsona'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.
ExamplesBelow is a screen shot of a small fragment in a Word document, illustrating the essentials of this feature. If you like, you can download the template that produced this screenshot. 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." As another example, you can use conditionals to generate the correct signature text in an acknowledgement letter, along the following lines:
«IF Oppty_Amt >= 500»John Doe, President «ELSE IF Oppty_Amt >= 250»Jane Doe, VP Sales «ELSE»Jill Doe, Director «ENDIF»
How to create a conditional directiveIn Microsoft Word, you would use the usual menu choices of Insert - Quick Parts - Field to insert a merge field within which you would place the text of the conditional directive. You can view an example animation showing how to create these directives using Word.
Structure of the IF directiveThe IF directive must be of the very specific form
IF templateField operator value
templateFieldis a merge field name,
operatoris a comparison operator, and
valueis the value with which to compare the merge field.
- The letters IF must be in upper case, followed by the template field, and optionally an operator and value, separated by spaces.
templateFieldmust include only letters, numerals, colons and underscores, no other characters. Thus spaces, for example, are forbidden in the
templateField. But references to aggregation fields are allowed.
operator, if present, must be one of the following six:
< less than <= less than or equal = equals != not equal to >= greater than or equal > greater than
valuemust be either a string surrounded by double quotes or a number.
templateFieldin 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
| Valid: tests whether |
| Valid: tests whether the sublist named |
|Invalid: embedded space in template variable|
|Invalid: missing closing quote|
|Invalid: IF is not in upper case|
Special case: Testing for empty fieldsWhen 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 spacesIf 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.
If you want to use this technique, use a line break, not a paragraph break. You can insert a line break in Word by typing Shift-Enter. If you use a paragraph break instead (by just pressing Enter without the Shift key), you might find that under some data conditions, the resulting output Word document becomes un-openable. This is because, when the IF condition fails, the end-of-paragraph marker will not be generated, even though a start-of-paragraph marker has been generated before the IF. So the output document has invalid markup, and Word will produce an error when you try to open it.
Constraints and notes
- Every IF field in the document template must be followed by a matching ENDIF directive. The content between those two fields is included or excluded based on whether the condition of the IF directive is met.
- The ELSE IF and ELSE parts of an IF construct or optional. E.g., you can have code that looks like
IF .... ENDIFwithout any ELSE IF or ELSE parts.
- The ELSE, ELSE IF and ENDIF directives must all be in upper case.
- For a particular IF, you can include as many ELSE IF directives as you want, as long as they are all between the IF and the corresponding ENDIF. But you can have no more than one ELSE directive for a given IF. Moreover, that one ELSE (if present) must be the last directive for its IF block, i.e., you cannot (for example) have an ELSE IF between an ELSE and its ENDIF.
- You can include IF directives within IF directives. For example, the following structure is perfectly valid. Notice in this example that the IF Hour condition is within an ELSE IF part, but has its own ENDIF. Note also that you can include, within the IF or ELSE parts, not just plain text but merge fields as well. For example, the conditional below includes the CONTACT_NAME and MESSAGE_FROM_CONTACT values only if the MESSAGE_FROM_CONTACT value is available:
- If Apsona recognizes a merge field as one of the four if-then-else directives, that merge field will not appear among the mappable fields. But if a merge field is not recognized, e.g., because that doesn't match the required structure of one of these directives, the merge field will appear in the list of mappable fields in step 2 of the merge action builder. This will be an indication that something is wrong about the directive.
- Conditional directives are not supported for merge fields within sublists.
- When using a conditional with a TableStart/TableEnd pair (where you want to show/not show the sublist based on a condition), make sure to put the ENDIF directive on a separate line after the TableEnd. If you put it on the same line, the Document Generator cannot align the conditionals correctly within the template structure, and this will result in generated files being un-openable. See screenshot below.
TroubleshootingYou might see an error popup with an error like
Found 'ENDIF' without a matching IF field, even though it looks like you have all your IFs and ENDIFs lined up. The error indicates that the Document Generator could not recognize the IF field you provided. In such a situation:
- Ensure that your IF directive confirms to the rules for valid directives described above.
- If using Microsoft Word merge fields (as against LibreOffice-style angle brackets) for your fields, ensure that the IF condition you see when you
edit the field (via right-click - Edit Field) matches what you see in the Word display. If they don't match, remove and rebuild the field. This
situation can arise because of the way in which Word stores fields internally. Below is an
example screenshot showing what Word displays when editing the document:
And below is what it shows when you right-click on the IF field and select "Edit Field":