Conditional Logic
iText DITO allows you to define logic in your output templates to insert content conditionally in generated PDF documents. Conditions can be either based on text, numbers or booleans (true/false fields).
Text-based Conditions
Text-based conditions evaluate whether a textual data element (e.g. the country of residence of a customer) has a specific value (e.g. United States) or not. If at runtime the condition resolves as true, then the selected element or substring will be included in the document. If the condition resolves to false, the conditional selection will be omitted, and the rest of the document will reflow.
The example below shows the three-step process of creating a text-based condition, using the condition settings wizard in the iText DITO Editor.
Step 1: Select any element or substring
The first step in the process consists of indicating which piece of content should be inserted conditionally. This can be an element from the template elements tree or a substring of a rich text element. Switch to data mapping mode via the command bar and make your selection on the editing canvas.
Step 2: Make content conditional
With the element or the substring selected in the data mapping mode, click the double arrows icon in the command bar at the top of the screen. This will activate the condition settings wizard that will guide you through the process of defining the text-based condition.
Step 3: Define the condition
In the wizard that opens up, you can select the data field that you want to evaluate, use it as text, select the operator and insert a value to compare it against. In the example below you will check whether the value of the field {{customer.country}} is equal to "United States". If that condition returns true, then the rich text element selected in step 1 will appear in the generated document, if the condition does not return true, it is left out.
In the resulting document, when generated for a customer that does not reside in the United States, the selected fragment will not be included.
Number-based Conditions
As well as text-based conditions, you can also evaluate a field against a numerical value. Depending on the validation outcome, selected content will be inserted in the generated documents or left out.
By means of example, in an invoice template you can make a table row that contains a discount amount appear only if a discount is given. The process has three steps.
Step 1: Select any element or substring
In the example below the selection is a table row element.
Step 2: Make content conditional
With the table row element selected in data mapping mode, click the double arrows icon in the command bar at the top of the screen. This will activate the condition settings wizard that will guide you through the process of defining the number-based condition.
Step 3: Define the condition
In the wizard that opens up, you can select the data field that you want to evaluate, use it as Number, select the operator and insert a value to compare it against. In the example below you will check whether the value of the field {{discount}} is greater than 0. If that condition returns true, then the table row element selected in step 1 will appear in the generated document, if the condition does not return true, it is left out.
If a document is generated with this template based on a data set that has a value which is not greater than 0 for the {{discount}} field, then the entire row that contains the data binding of the discount will be omitted and the rest of the document will reflow accordingly.
True/False (Boolean)-based Conditions
Boolean-based conditions follow the same pattern as number or text-based conditions.
In the third step though, you select True/False (Boolean) in the Use as selector and then select the appropriate operator and value.
The text 'Contract renewal fulfilled' will only be printed if the value of boolean field renewal_payment_received equals 'True'.
Conditions Pane
You can easily navigate the conditional sections in your template via the Conditions pane in the Data Connections panel that you see to the right of the editing canvas in data mapping mode. From this list of conditions you can edit or delete conditions at any time.
