Using functions

Variables are useful to insert information in your document when you are using a template. However, the values entered in a variable are not always exactly what we want to insert in the document. You may want to do some formatting first. This is what functions are for.

Let’s say you want to display the client_name in CAPITAL LETTERS.

You could fill the variable’s value in CAPITAL LETTERS, but:

• It’s error-prone; it’s easy for the template’s user to forget or not know.
• If you need the client_name in its official format elsewhere in the template, you would have to enter a value for both client_name and client_name_CAPITAL each time.

A more practical way to deal with this is to use a function to transform client_name before displaying it.

Let’s see this in action.

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. Locate the <# client_name #>

The content of the left box should be:

Hello <# client_name #>! This is an example.

Let’s focus on the <# client_name #>:

• the <# marks the start of the command.
• the client_name, because it starts with a lowercase letter, is a variable.
• the #>, marks the end of the command.

Note: The spaces after <# and before #> are not needed, but are recommended because they make it easier to read the template.

3. Use a function

We would like to display the client_name in CAPITAL LETTERS. We’ll use the UPPER function for this.

To use a function, you first write the function’s name, then open a parenthesis (, then you provide the values to the function, and you finish with a closing parenthesis ).

So for our case, the whole command should be: <# UPPER(client_name) #>.

For tutorial purpose, edit / type it out manually (instead of copying/pasting). As you type, you will notice error messages appearing at the bottom right. This is normal; until you are done writing the whole thing, the command is not valid. For example: <# UPPER(client is not valid as it’s missing a closing parenthesis ) and an end of command #>.

You should end up with this:

Hello <# UPPER(client_name) #>! This is an example.

The right box should now contain ANNA LOGWATCH in capital letters. Feel free to change the client_name variable’s value in the bottom left to test it out.

4. Giving values directly

Functions don’t have to receive variables. You can use a function by giving it with values directly. For example, insert this:

<# UPPER("hello") #>

The way this works is that the quotes (") around something indicate to DocuMold that it is a piece of text. This is needed to distinguish UPPER("hello") which uses the text hello from UPPER(hello) which uses the content of the variable named hello.

We are using the UPPER function on the text hello. You should see the right box containing: HELLO.

Anywhere you use a variable, you can place a value directly instead.

5. A function using more than one value

Some functions can accept multiple values and others need none. It depends on the function and what it does.

An example of a function that takes multiple values is TEXTAFTER(text, delimiter). It receives a text and a delimiter within that text. It returns the part of the text that is after that delimiter in the text.

DocuMold uses a comma (and a space) to separate the values, this makes the different parts clearer for the reader (when editing the template) and for DocuMold.

Try it; add this to the sandbox:

<# TEXTAFTER(text, delimiter) #>

You will see that you now have two variables at the bottom left, and nothing new is shown in the right box. This is because the value of delimiter, which by default is the text (delimiter) is not inside the value of text, which is the text (text).

If you change the value of the variable text to be “message”, and the value of the variable delimiter to be the letter s. Then in the right box, you would see sage appear.

Again, the function can receive values directly. Try this:

<# TEXTAFTER(text, "/") #>

Write part1/part2 as value for the text variable in the bottom left, then the right box will only contain part2.

You can use any variable names. text and delimiter are just names used to clarify what those received values do when describing the function.

6. Multiple functions at once

You can also pass the result of a function to another one. Try this in the sandbox:

<# TEXTAFTER(UPPER(text), "/") #>

With part1/part2 as value for the text variable, you will see PART2 in the right side.

Conclusion

Functions are a powerful tool to transform and generate new values.

DocuMold has a lot of functions. Most of them have the same name and behave the same as in Excel.

You can find them all in the documentation in the menu bar on the left of this page, under “All functions”.

The next tutorial introduces conditional content, which let you hide (remove) part of your template.