Skip to main content

Templates

MindTheDoc templates are simply HTML files, they need to have a .html extension in case you put them in a ZIP file.

A template contains variables, which get replaced with values when a template is rendered. It also supports tags to control the logic of the template.

Below is a minimal template:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>My Document</title>
</head>
<body>
    {# a comment #}
    <h1>{{ a_variable }}</h1>
    <ul>
    {%- for item in list_entries -%}
        <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
    {%- endfor -%}
    </ul>
</body>
</html>
Note

As you can see there are a few kinds of delimiters. The delimiters are:

  • {% ... %} for Statements
  • {{ ... }} for Expressions to print to the template output
  • {# ... #} for Comments not included in the template output

An example of the data input for this would be:

{
    "a_variable": "Awesome tools",
    "list_entries": [
        {
            "href": "https://www.tresorbase.com/",
            "caption": "Tresorbase"
        },
        {
            "href": "https://askfino.com/",
            "caption": "AskFino"
        },
        {
            "href": "https://mindthedoc.com/",
            "caption": "MindTheDoc"
        }
    ]
}

The data object should set the value of all the template variables in expressions and statements.

Variables​

Template variables are defined by the data object passed to generate the document. Variables may have attributes or elements on them you can access too.

You can use a dot (.) to access attributes of a variable.

The following line shows how to place the value of a variable in a template:

{{ invoice.number }}

It’s important to know that the outer double-curly braces are not part of the variable, but the print statement.

If a variable or attribute does not exist, you will get back an undefined value. An undefined value results in an empty string if you just need to print it, but could cause an error if you put it in an if statement, for example.

A data example to fill up this template variable would need to be:

{
    "invoice": {
        "number": "INV-2023-0001"
    }
}

Comments​

To comment-out part of a line in a template, use the comment syntax which is by default set to {# ... #}. This is useful to comment out parts of the template for debugging or to add information for other template designers or yourself:

{# note: commented-out template because we no longer use this
    {%- for user in users -%}
        ...
    {%- endfor -%}
#}

Control structures​

A control structure refers to all those things that control the flow of a program - conditionals (i.e. if/elif/else) and for-loops. Control structures appear inside {%- ... -%} blocks.

For loops​

Loop over each item in a sequence. For example, to display a list of members provided in a variable called members:

<h1>Members</h1>
<ul>
{%- for member in members -%}
  <li>{{ member.name }}</li>
{%- endfor -%}
</ul>

As variables in templates retain their object properties, it is possible to iterate over objects:

<dl>
{%- for key, value in things.items() -%}
    <dt>{{ key }}</dt>
    <dd>{{ value }}</dd>
{%- endfor -%}
</dl>

The object to fill up this template would look like this:

{
    "things": {
        "Fruit": "Orange",
        "Animal": "Dog"
    }
}

If statements​

The simplest form of the if statement, can be used to test if a variable is defined, not empty and not false:

{%- if members -%}
<ul>
{%- for member in members -%}
  <li>{{ member.name }}</li>
{%- endfor -%}
</ul>
{%- endif -%}

An example which would result in filling up this snippet would be:

{
    "members": [
        {
            "name": "Max"
        },
        {
            "name": "Sonia"
        }
    ]
}

An empty members object would look like:

{
    "members": []
}

For multiple branches, elif and else can be used:

{%- if user.has_account -%}
    Hello {{ user.name }}.
{%- elif user.is_activated -%}
    Please activate your account.
{%- else -%}
    Sign up here!
{%- endif -%}

An example object would be:

{
    "user": {
        "has_account": true,
        "name": "Laura",
        "is_activated": true
    }
}