Logo Docs
Logo Docs

Conditional content

Conditions are an important part of document templates. They allow you to pick a between values and to hide content. Let’s say you want to show a sentence only if client_country is “Canada”.

1. Go to the sandbox’s page

We will use the sandbox for this tutorial. If you are not familiar with it, please read the Using the sandbox tutorial.

Open the sandbox:

  1. Login on https://documold.com
  2. Click on “Sandbox” in the menu on the left
  3. Click on “Reset” at the top so that you start with the content that this tutorial expects

2. For a few words

For a simple sentence, the IF function can be enough.

It looks like this: IF(condition, value_if_true, value_if_false). The condition is evaluated and if it is TRUE, value_if_true is returned, otherwise value_if_false is returned.

Note: value_if_false is optional.

In the sandbox, enter this in a new line in the left box of the sandbox:

<# IF(client_country = "Canada", "You are in Canada!") #>

The right box won’t show anything yet. The equal sign (=) evaluates to true only if the values on each side are the same.

Now in the bottom left, set the value of client_country to Canada (the case is important, CAPITAL “C”). You should then see the “You are in Canada!” appear in the right box.

To display something when client_country is not “Canada”, add another comma then the desired text. For example:

<# IF(client_country = "Canada", "You are in Canada!", "You are not in Canada") #>

The IF function is useful for short sentences with no formatting (as above). Note:

  • The examples used values directly, but just like any functions, you can use variables and other functions in any of them.
  • Its result can be used in any command, it acts like any function. So this is valid: 
    <# UPPER(IF(use_full_name, full_name, first_name)) #>

3. For a whole section

When the content to hide/show is bigger, such as whole paragraphs and when the content contains formatting, the IF function will not do the job.

Instead, the @IF and @ENDIF actions can be used to wrap whole sections of your document. We’ll explain soon.

Add these new lines in the left box of the sandbox:

<# @IF(client_country = "Belgium") #>
Since the client is from Belgium, these extra steps are needed:

* Currency conversion
* Consider time zones when making appointments
<# @ENDIF #>

Now change client_country’s value to Belgium to see your content appear on the right side.

4. Actions…?

Actions look like functions, but instead of returning a value, they tell DocuMold what a command must do.

Actions always start with an at sign @. A command can only contain one action and it must be the first thing in it. If no action is specified, DocuMold treats the command as a @WRITE action, which writes the result to the document as we’ve seen so far.

There might be a little confusion between IF and @IF. It’s the only case where an action and a function have the same name. IF is a function, so it can be used anywhere, and it returns a value to be used by other functions/commands. @IF is the action, which can hide entire sections of your document.

To clarify:

  • <# ... #> is a command
  • @IF(...) is an action
  • UPPER(...) is a function
  • client_name is a variable

Many actions are available in DocuMold, the tutorials will progressively go over them.

5. Different sections

To show different content when the condition is false, use the @ELSE action. It must be between a @IF and @ENDIF actions.

Add this before the <# @ENDIF #>:

<# @ELSE #>
There are no extra steps for the client's country.

Overall, this should look like:

<# @IF(client_country = "Belgium") #>
Since the client is from Belgium, these extra steps are needed:

* Currency conversion
* Consider time zones when making appointments
<# @ELSE #>
There are no extra steps for the client's country.
<# @ENDIF #>

So now, if client_country is different from Belgium, the “There are no extra steps for the client’s country.” should appear in the right box.

6. A second country

Let’s have a second country for which we want different content. Canadians are nice, let’s mention the rebate we have for them!

We will now use the @ELSEIF action. Add this before the <# @ELSE #>:

<# @ELSEIF(client_country = "Canada") #>
Offer a gift to Canadian customers.

Resulting in:

<# @IF(client_country = "Belgium") #>
Since the client is from Belgium, these extra steps are needed:

* Currency conversion
* Consider time zones when making appointments
<# @ELSEIF(client_country = "Canada") #>
Offer a gift to Canadian customers.
<# @ELSE #>
There are no extra steps based on the client's country.
<# @ENDIF #>

We now have two special cases for client_country, which show different sections, and a final case that is displayed when the country is something else.

  • Just like @ELSE, @ELSEIF goes between a @IF and a @ENDIF.
  • You can have multiple consecutive @ELSEIF.
  • If you also use a @ELSE, the @ELSE must be after all @ELSEIF.

Conclusion

Conditions are an important tool to make the templates generate exactly what you want. If you want more information about @IF and its related actions, this explanation focuses on the subject: Clarifying @IF

In this tutorial, all we’ve used as a condition was =. More options are available, but they won’t be shown in these tutorials. To learn more, read this explanation: Conditions.