Skip to main content

The Jinja2 Templating Language

Jinja2 plays the same role inside Microsoft Word docx templates that Mako plays inside the interview file.

Jinja was originally created as a templating language for Django. Docassemble's version of Jinja is not quite the same; it's a variation built for docx-template. It's useful to keep this in mind if you are trying to use an advanced feature and find that it doesn't work.

Jinja statements allow you to:

  1. Insert variables
  2. Use conditional text
  3. Use control structures to display repeated variables

Insert variables

To insert a variable into your document, surround it with double curly braces, like this: {{ variable_name }}.

It's also possible to include Python code in the place of the variable name. For example, if you had assigned the value of my_variable as below:

my_variable = "lowercase name"

Then you could use the .capitalize() method of a string inside Jinja tags to make sure that it started with a capital letter, regardless of how the user entered it inside your application:

Dear {{ my_variable.capitalize() }}:

I am writing to tell you...

Use conditional text

One of the most common uses of Jinja tags inside a docx template is to insert conditional text. There are two types of conditionals: in-line, and paragraph/bullet level conditionals.

In-line conditional statements

Jinja in-line conditionals are started with a curly brace and a % symbol, like {% if condition %} and closed with {% endif %}. You can optionally include both {% elif %} and {% else %} tags.

You are {% if person.age_in_years() < 13 %} a child {% elif person.age_in_years() < 20 %} a teenager {% else %} an adult. {% endif %}

Paragraph-level conditional statements

Sometimes you want to hide an entire paragraph if a certain condition is met. One time you may want to use this when several optional items are shown on a list. In this case, you use a slight variation: {%p if... %}.

* Apple
* {%p if likes_bananas %}
* Bananas
* {%p endif %}

If you leave out the p, you would have an empty line after Apple. Using p tells Docassemble to remove that line from the document.

Make sure you use the {%p endif %} form to close the statement. Otherwise, Docassemble will raise an error that there is an unmatched if statement.

Use control structures

Control structures use the same syntax as conditional statements, surrounded by {% %} or {%p %}. You can use the same control structures (for and while) in Jinja that you can use in Python and wherever you can use Mako statements.

{%p for fruit in fruits %}
* {{ fruit }}
{%p endfor %}

Further reading