Overview

Many parts are interacting in DocuMold. This overview goes over the basics, it has two goals:

• if you’ve followed the tutorials, it’s a review with extra details
• otherwise, a starting point for grasping how DocuMold works without following the tutorials

DocuMold generates new Word documents from templates you make. The templates are regular Word documents, but contain commands that modify the resulting document, such as inserting or removing content.

To better explain everything, understanding the basic workflow is important:

Preparation:

1. Prepare your Word template, using commands where you want content automatically inserted or hidden
2. Save the template on your computer

Then, when you need a document:

1. Pick your template (from your computer)
2. Provide the information needed by the template in the form DocuMold displays
3. Download the resulting document
4. Use the document as is or edit it with Word

Commands and variables

Here is something you could find in a template:

This is an agreement between <# client_name #> and ...

The magic lies in the <# and #>, they mark the start and end of every DocuMold command. In the above example, the command is <# client_name #>. This is the most common kind of command, a simple “write something here”. That something is a variable, named client_name, which you will be asked to provide a value for when you generate a document from the template.

If you enter “Anna Logwatch” as client_name, the generated document would contain:

This is an agreement between Anna Logwatch and ...

Note: Commands can be anywhere in your document (in the middle of a paragraph, in a table, etc.).

Note: Variables start with a lowercase letter and contain letters, numbers and underscores (_).

Functions

You may need to format what is displayed from a variable. For our example, let’s say you want to display the client_name in all caps.

Using the UPPER function, here is how you can do it:

This is an agreement between <# UPPER(client_name) #> and ...

The UPPER function turns all letters into uppercase ones. Note: The parentheses after UPPER and around client_name mark the values used by the function.

Now, entering “Anna Logwatch” would generate this:

This is an agreement between ANNA LOGWATCH and ...

Notes:

• Functions’ names are written in ALL CAPS (there are rare exceptions).
• A function must be followed by an opening parenthesis (.

Another common function is IF. It needs:

• a condition
• a value to choose if the condition is true
• optionally, a value to choose if the condition is false

It looks like this: <# IF(show_dollar_sign, "$") #>.

• The comma (,) separates the different values the function receives.
• The two quotes " mark a piece of text to be used as-is by DocuMold; "$" means: the text $.

Back to the example, if show_dollar_sign is true, then there will be a dollar sign, otherwise there won’t.

Here is the 3-value version: <# IF(picked_yes, "yes", "no") #>. It would write <# IF(picked_yes, "yes", "no") #> or no based on the picked_yes variable.

DocuMold had many more functions, you can find them in the menu on the left side of this page, under “All functions”.

Note: Values that functions receive can come from another function: <# UPPER(LEFT(client_name, 10)) #>. Here, LEFT returns the first 10 characters, which are given to UPPER to turn them uppercase. For “Anna Logwatch”, the result would be ANNA LOGWA.

Actions

By default, commands write values to the document, but other actions are available.

For example, there is the @IF action which receives a condition and either shows or hide the content between that command and the @ENDIF command that follows. This is helpful to conditionally hide large sections of content or images, for example.

Here is how that looks:

Something before

<# @IF(client_age < 30) #>
WARNING:
There is an extra verification to make since the client is less than 30 years old.
<# @ENDIF #>

Something after

The condition uses the < operator to compare numbers. It evaluates to true when the client_age is less than 30. We’ll talk more about operators later.

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.

If the client_age you enter when generating a document is less than 30, then the result would be:

Something before

WARNING:
There is an extra verification to make since the client is less than 30 years old.

Something after

And if client_age is 30 or above, the result would be:

Something before

Something after

You might be surprised by the spacing in this last result. There was a blank line before the <# @IF... #> and one after the <# @ENDIF #>, but there is only one in the generated document. When DocuMold removes a command and puts nothing in its place, only the spacing before the command or the one after is kept, whichever one is bigger. This also applies when the command is replaced by an empty text, so <# something #> with something being is an empty text.

When there are many different cases to handle, @ELSEIF and @ELSE can be used with @IF and @ENDIF.

DocuMold has many more actions available, you can find them in the menu bar on the left side of this page, under “All actions”.

Actions versus functions

Visually, actions always start with an at sign @. The rest of it looks just like a function: ALL CAPS words, then an opening parenthesis (, then values, then the closing parenthesis ).

Note: A function that doesn’t receive values still needs parentheses: TODAY(), but an action doesn’t: @ENDIF.

What they do is different:

• A function’s job is to provide a new value from the ones it has received.
• An action’s job is to decide what DocuMold should do with the values.

Actions do not return values, therefore they cannot be used inside a function’s values. Actions can only be placed after the <# , at the beginning of a command.

Examples of actions “doing things” with the values:

• If you don’t specify an action, DocuMold will write the value into the generated document.
• After an @IF action, DocuMold knows there should be a @ENDIF and will use the value given to @IF to decide if it should erase part of your document or not.
• The @TEXT_QUESTION action, tell DocuMold how to ask for a value from the user when generating a document from a template.

The only action and function that share their name is @IF and IF. Luckily, they don’t receive the same number of values.