Conditional Expressions

The Encodian population engine supports conditional expressions which enable you to add logic to your document to evaluate defined criteria to ascertain whether certain tokens (and related data) should be inserted into the document.

This article covers the following topics and examples:

Conditional Expression Syntax Overview

Example #1 - Basic

Example #2 - Advanced

Example #3 - Tables

Example #4 - Date Time Values

Checking for Null Values

Checking for Null Arrays

Conditional Expression Operators

Conditional Expressions within foreach Loops

Conditional Expression Syntax Overview

Conditional expressions conform to common logical syntactical constructs, see below:

<<if [conditional_expression1]>>
  Show this data
  <<elseif [conditional_expression2]>>
    Show This data
  <<else>>
    This this data
<</if>>

Example #1 - Basic

Example Document: Encodian - Template Syntax - Conditions Basic.docx

Example JSON Data:

{
  "companyName": "Encodian",
  "invoicePaid": true,
  "invoiceOverdue": false,
  "invoiceDue": "2021-06-01",
  "invoiceValue": 10000
}

Configure the document with required conditional expressions and content:

<<if [invoicePaid == false]>>
The invoice has not been paid.
<<else>>
The invoice has been paid.
<</if>>

This generates the following output:

Example #2 - Advanced

Example Document: Encodian - Template Syntax - Conditions Advanced.docx

Example JSON Data:

{
  "companyName": "Encodian",
  "invoicePaid": false,
  "invoiceDue": "2021-06-01",
  "invoiceValue": 10000,
  "generatedOn": "2021-05-19"
}

Configure the document with required conditional expressions and content:

<<if [invoicePaid == false && invoiceDue < generatedOn]>>
  The invoice is unpaid and overdue.
<<elseif [invoicePaid == false && invoiceDue > generatedOn]>>
  The invoice is unpaid and due <<[invoiceDue]:"yyyy.MM.dd" >>
<<else>>
  The invoice is paid.
<</if>>

This generates the following output:

Example #3 - Tables

Example Document: Encodian - Template Syntax - Conditions Tables.docx

Example JSON Data:

{
  "companyName": "Encodian",
  "contracts": [
  {
    "customerName": "Microsoft",
    "value": 100000.00,
    "expires": "13/06/2021"
  },
  {
    "customerName": "Encodian",
    "value": 6872500.00,
    "expires": "18/02/2029"
  },
  {
    "customerName": "Heritage",
    "value": 13549.35,
    "expires": "6/12/2025"
  }
 ]
}

Configure the document with required conditional expressions and content:

Row 1 > Column 1: <<foreach [contract in contracts]>><<if [contract.customerName!=”Encodian”]>><<[ contract.customerName]>>
Row 1 > Column 2: <<[contract.expires]:"yyyy.MM.dd">>
Row 1 > Column 3: <<[contract.value]>><</if>><</foreach>>
Row 2 > Column 1: <<[contracts.Sum(c =>c.value)]>>

This generates the following output:

Example #4 - Date Time Values

Example Document: Encodian - Template Syntax - DateTime.docx

Example JSON Data:

{
   "commenced": "2020/10/29",
   "expires": "2021/10/28",
}

Configure the document with required conditional expressions and content:

<<if [expires.ToString() == ""]>>
    Expires On: None
<<else>>
    Expires On: <<[expires]:"yyyy-MM-dd">>
<</if>>

NOTE: You must use the ToString() method to compare a DateTime value with a string. If this step is not performed the engine will throw an error stating that a DateTime object cannot be compared with a string.

This generates the following output:

Checking for Null Values

By default the 'JSON Parse Mode' is set to 'Standard' and therefore the populate engine will parse null values as empty strings. When checking for null values we recommend setting the 'JSON Parse Mode' option to 'Strict'.

Example JSON Data:

{ "value": null }

The following options are available for performing a null check:

Checking for Null Arrays

Please view the repeating content syntax article, section Repeating Content – Checking for Null Arrays

Conditional Expression Operators

The following table contains all operators that the Encodian population engine supports

• Binary:  * / % + - << >> < > <= >= == != & ^ | && || ??
• Primary:  x.y x?.y f(x) a[x] a?[x] new
• Unary:  - ! ~ (T)x
• Ternary:  ?:

The population engine follows operator precedence, associativity, and overload resolution rules declared at C# Language Specification 5.0 while evaluating template expressions. However, please consider the following limitations considering the specification:

• Implicit user-defined conversions are supported only when specified explicitly.
• The indexing of multi-dimensional arrays is not supported.
• Whereas the object initializer syntax is supported (including objects of anonymous types), the collection initializer syntax is not.

Conditional Expressions within foreach Loops

In the Encodian Populate Word template system, conditional expressions within a foreach loop cannot reference or compare values that are external to the loop (i.e., values or properties that exist outside the scope of the loop). This limitation arises because each iteration of the loop is isolated.

To address this limitation, you can use Variables initialised before the loop.

An example might be to insert a page break but skip the page break on the last item. It is not possible to compare Item to Items.Last() within the foreach loop as the items.last() is external. Instead, initialise a variable:

<<var[LastItem = items.Last()]>>

You can then use the following conditional expression inside the foreach loop:

<<if[item != LastItem]>>

Syntax Support

Please refer to our Template Design forum where our support team can help with template syntax / you can see solutions to common use cases.