Commands

Commands are pieces of text wrapped with <# and #> that DocuMold executes when generating a document. They are what gives DocuMold its power.

Just like comments, commands can be placed anywhere in the template: in the middle of a paragraph, of a table, etc. The only limitation is that a comment cannot be in a command and vice versa.

Examples

Here are some examples we’ll explore:

  • <# client_name #>
  • <# UPPER(client_name) #>
  • <# nb_adults + nb_children #>
  • <# TEXTBEFORE(serial, "-") #>
  • <# @IF(age < 18) #>
  • <# @ENDIF #>

As mentioned, the commands all start with <# and end with #> so that DocuMold knows what to process.

<# client_name #>

This command contains only client_name.

Words that start with a lowercase letter are variables. The underscore (_) allows writing multiple words in a variable’s name.

For this case: when generating a document from the DocuMold template, the value of the variable will overwrite the whole command in the document.

Hello <# client_name #>,

With a client_name of “Anna Logwatch” results in:

Hello Anna Logwatch,

<# UPPER(client_name) #>

We can still see the client_name variable in the command above, but now it is given to the UPPER function. Functions are in ALL CAPS letters and are a single word or many with underscores (_). Functions receive one or multiple values and give a new value.

Parentheses ( and ) are placed around the values the function receives.

For this case: when generating a document from the DocuMold template, the value of client_name is given to the UPPER function, which returns the same text in ALL CAPS, which will overwrite the whole command in the document.

Hello <# UPPER(client_name) #>,

With a client_name of “Anna Logwatch” results in:

Hello ANNA LOGWATCH,

<# nb_adults + nb_children #>

Here, we have 2 variables, nb_adults and nb_children. The plus sign + does an addition of the values before and after it.

Operators, such as the plus sign +, behave just like functions in that they receive values and provide new ones, but they don’t use parentheses to receive values. When multiple operators are used in a row, they are evaluated in the same order as in math: multiplication is calculated before addition. Parentheses ( and ) can be used to specify the priority if needed.

For this case: when generating a document, the sum of both variables will overwrite the whole command in the document.

Number of tickets: <# nb_adults + nb_children #>

With a nb_adults of 2 and nb_children of 1 results in:

Number of tickets: 3

<# TEXTBEFORE(serial, "-") #>

Here we have a function that receives 2 values. A comma , is used to separate the values it receives within the parentheses ( ).

This is the TEXTBEFORE function, which extracts the part of a text that is before a delimiter. In this case, the text is in the serial variable and the delimiter is a -.

You might notice the double quotes (") around the dash (-). The double-quotes surround a piece of text you want to use as-is. So "-" means the text -. Without the ", text could look like variables, variables, operators and other symbols that DocuMold treats specially. So to avoid that, any text you want to be used as-is must have double quotes around it.

So <# TEXTBEFORE(serial, "-") #> uses content of the variable serial, while <# TEXTBEFORE("serial", "-") #> uses the text serial only, which, as we can see, doesn’t contain any dash (-), but DocuMold just does what it’s told.

For this case: when generating a document, the text before the first dash (-) in the serial variable will overwrite the command in the document.

Model number: <# TEXTBEFORE(serial, "-") #>

With a serial of “msk32-28371346”:

Model number: msk32

<# @IF(age < 18) #> and <# @ENDIF #>

The first command above might look like a function, and there is an IF function, but this is actually the @IF action. Actions all start with an at sign (@). They tell DocuMold what to do with the values.

Actions are always placed at the beginning of a command, after the <#.

None of the examples before this one specified an action, so the default one was used: write the value in the document in place of the command.

The @IF action receives one value, the condition. You then place regular content after the command, then another command: <# @ENDIF #>.

When generating a document, if the condition is TRUE, the content will be displayed (and the two commands erased). If the condition is FALSE, then the content and the two commands will be erased.

For this case: when generating a document, if the age variable is less than 18, the content after the @IF command and until the @ENDIF is displayed. Otherwise it isn’t.

General information

<# @IF(age < 18) #>
Restrictions for minors:
* may not go to the bar area.
...
<# @ENDIF #>

Some more information

With age of 20 results in:

General information

Some more information

With age of 15:

General information

Restrictions for minors:
* may not go to the bar area.
...

Some more information

Noteworthy details

Spaces and line changes in a command

Spaces and line changes can be placed anywhere in a command as long as you are not splitting a name (of a variable, function or action) or an operator (such as >=).

So these are invalid:

  • <# UP P ER(client_name) #> since UPPER must not have spaces
  • <# IF(age > = 18, "adult") #> since > and = must be adjacent to form the >= operator

Line changes can make long commands easier to read and modify. As an example, this line is often considered harder to read:

<#IF(age>=18,"adult")#>

While the extra spaces in this line help distinguish the different parts of the command:

<# IF(age >= 18, "adult") #>