Conditions

Many tools in DocuMold expect a condition:

The IF and IFS functions
The @IF and @ELSEIF actions

If you are not yet familiar with these functions and actions, it may be helpful to first read Conditional content which introduces most of them.

This document dives into what can be used as conditions and how to make more complex ones.

What makes a condition

In DocuMold, a condition is really just something that evaluates to either TRUE or FALSE. These two values are the only ones that can be given to IF and every other tool that expect a condition.

In the tutorials, the conditions almost always used the = operator. For example:

<# @IF(client_country = "Canada") #>
A Canadian
<# @ENDIF #>

But there are many more tools you can use for conditions, we’ll list them shortly.

Since conditions can only return TRUE or FALSE, the explanations below are shortened by only mentioning one of the 2 cases. There is an unwritten “otherwise, returns the other value”.

More condition operators

Operators are similar to functions. They receive values and provide a new value. The difference is that the values received are the ones on its left and on its right.

Here is a list of the operators you can use as conditions.

First, these operators can be used with any kind of values:

left = right: this is TRUE if left is equal to right
left <> right: this is TRUE if left is different from right

However the following operators are only available when left and right are numbers:

left < right: this is TRUE if left is smaller than right
left > right: this is TRUE if left is greater than right
left <= right: this is TRUE if left is smaller or equal to right
left >= right: this is TRUE if left is greater or equal to right

For left and right to be numbers (instead of text containing digits), you must either:

use the @NUMBER_QUESTION to set the variable as a number
write a numeric value directly in the code without quotes, ex: age >= 18
use a function which converts to a number: NUMBER(text_containing_numbers)
use a function which returns a number: FIND("every", "hello everybody") gives the position of the first text within the second one, which is the number 7

Here are examples of some of these different operators:

<# IF(age >= 18, "An adult", "A non-adult") #>

<# @IF(client_country <> "Canada") #>
A non-Canadian
<# @ENDIF #>

Functions as conditions

Some functions return either TRUE or FALSE; they can be used as conditions too. Some examples:

CAN_FIND(text_to_find, in_text): returns TRUE if text_to_find is in in_text, case sensitive
CAN_SEARCH(text_to_find, in_text): returns TRUE if text_to_find is in in_text, case insensitive
CONTAIN(list, value): returns TRUE if list contains the value

Here is an example:

<# @IF(CONTAIN(selected_perks, "wedding")) #>
A wedding is planned on....
<# @ENDIF #>

Combining conditions

You may want to combine multiple conditions. These 2 functions receive as many conditions as you want and return TRUE or FALSE:

AND(cond1, cond2...): returns TRUE if every condition is TRUE
OR(cond1, cond2...): returns TRUE if at least one condition is TRUE

You can also invert a condition with this:

NOT(condition): returns TRUE if condition is FALSE, returns FALSE if condition is TRUE

Full example:

<# @IF(AND(drinks_requested, age < 18)) #>
Sorry, but you are not allowed to drink alcoholic beverages.
<# @ENDIF #>

<# IF(OR(age >= 18, is_with_adult), "Is allowed on the harder tracks") #>

Variables as condition

If a variable’s value is TRUE or FALSE, it can be used as a condition directly.

Some ways this can happen:

@YES_NO_QUESTION action: the variable is set to either TRUE or FALSE
@PICK_ONE_QUESTION action: can set the variable to a value of your choice, which can be TRUE or FALSE Ex: @PICK_ONE_QUESTION(is_adult, choices: [["Adult", TRUE], ["Child", FALSE]])

Chaining operators

DocuMold allows you to “chain” condition operators. This is a small shortcut when you want to compare multiple values.

sample = dm_sample(%{
  <# IF(18 <= age < 65, "Regular adult") #>
}).test_with({age: 70}, %{
}).test_with({age: 19}, %{
  Regular adult
})

This condition would be TRUE if age is 18 or higher, but also smaller than 65.

Each operator is applied on the values to its left and right: 18 <= age and age < 65. The final result is TRUE if each operator resulted in TRUE.

The equivalent without chaining would be: