Expressions

Jinja allows basic expressions everywhere. These work very similarly toregular Python; even if you’re not working with Pythonyou should feel comfortable with it.

Literals

The simplest form of expressions are literals. Literals are representationsfor Python objects such as strings and numbers. The following literals exist:

  • “Hello World”:

  • Everything between two double or single quotes is a string. They areuseful whenever you need a string in the template (e.g. asarguments to function calls and filters, or just to extend or include atemplate).

  • 42 / 42.23:

  • Integers and floating point numbers are created by just writing thenumber down. If a dot is present, the number is a float, otherwise aninteger. Keep in mind that, in Python, 42 and 42.0are different (int and float, respectively).

  • [‘list’, ‘of’, ‘objects’]:

  • Everything between two brackets is a list. Lists are useful for storingsequential data to be iterated over. For example, you can easilycreate a list of links using lists and tuples for (and with) a for loop:
  1. <ul>
  2. {% for href, caption in [('index.html', 'Index'), ('about.html', 'About'),
  3.                          ('downloads.html', 'Downloads')] %}
  4.     <li><a href="{{ href }}">{{ caption }}</a></li>
  5. {% endfor %}
  6. </ul>
  • (‘tuple’, ‘of’, ‘values’):

  • Tuples are like lists that cannot be modified (“immutable”). If a tupleonly has one item, it must be followed by a comma (('1-tuple',)).Tuples are usually used to represent items of two or more elements.See the list example above for more details.

  • {‘dict’: ‘of’, ‘key’: ‘and’, ‘value’: ‘pairs’}:

  • A dict in Python is a structure that combines keys and values. Keys mustbe unique and always have exactly one value. Dicts are rarely used intemplates; they are useful in some rare cases such as the xmlattr()filter.

  • true / false:

  • true is always true and false is always false.

Note

The special constants true, false, and none are indeed lowercase.Because that caused confusion in the past, (True used to expandto an undefined variable that was considered false),all three can now also be written in title case(True, False, and None).However, for consistency, (all Jinja identifiers are lowercase)you should use the lowercase versions.

Math

Jinja allows you to calculate with values. This is rarely useful in templatesbut exists for completeness’ sake. The following operators are supported:

  • +

  • Adds two objects together. Usually the objects are numbers, but if both arestrings or lists, you can concatenate them this way. This, however, is notthe preferred way to concatenate strings! For string concatenation, havea look-see at the ~ operator. {{ 1 + 1 }} is 2.

  • -

  • Subtract the second number from the first one. {{ 3 - 2 }} is 1.
  • /
  • Divide two numbers. The return value will be a floating point number.{{ 1 / 2 }} is {{ 0.5 }}.
  • //
  • Divide two numbers and return the truncated integer result.{{ 20 // 7 }} is 2.
  • %

  • Calculate the remainder of an integer division. {{ 11 % 7 }} is 4.

  • *

  • Multiply the left operand with the right one. {{ 2 2 }} wouldreturn 4. This can also be used to repeat a string multiple times.{{ '=' 80 }} would print a bar of 80 equal signs.
  • Raise the left operand to the power of the right operand. {{ 2**3 }}would return 8.

Comparisons

  • ==

  • Compares two objects for equality.

  • !=

  • Compares two objects for inequality.
  • >

  • true if the left hand side is greater than the right hand side.

  • >=

  • true if the left hand side is greater or equal to the right hand side.
  • <

  • true if the left hand side is lower than the right hand side.

  • <=

  • true if the left hand side is lower or equal to the right hand side.

Logic

For if statements, for filtering, and if expressions, it can be useful tocombine multiple expressions:

  • and

  • Return true if the left and the right operand are true.

  • or

  • Return true if the left or the right operand are true.

  • not

  • negate a statement (see below).

  • (expr)

  • group an expression.

Note

The is and in operators support negation using an infix notation,too: foo is not bar and foo not in bar instead of not foo is barand not foo in bar. All other expressions require a prefix notation:not (foo and bar).

Other Operators

The following operators are very useful but don’t fit into any of the othertwo categories:

  • in

  • Perform a sequence / mapping containment test. Returns true if the leftoperand is contained in the right. {{ 1 in [1, 2, 3] }} would, forexample, return true.

  • is

  • Performs a test.

  • |

  • Applies a filter.
  • ~
  • Converts all operands into strings and concatenates them.

{{ "Hello " ~ name ~ "!" }} would return (assuming name is setto 'John') Hello John!.

  • ()
  • Call a callable: {{ post.render() }}. Inside of the parentheses youcan use positional arguments and keyword arguments like in Python:

{{ post.render(user, full=true) }}.

  • . / []
  • Get an attribute of an object. (See Variables)

If Expression

It is also possible to use inline if expressions. These are useful in somesituations. For example, you can use this to extend from one template if avariable is defined, otherwise from the default layout template:

  1. {% extends layout_template if layout_template is defined else 'master.html' %}

The general syntax is <do something> if <something is true> else <dosomething else>.

The else part is optional. If not provided, the else block implicitlyevaluates into an undefined object:

  1. {{ "[{}]".format(page.title) if page.title }}

Python Methods

You can also use any of the methods of defined on a variable’s type.The value returned from the method invocation is used as the value of the expression.Here is an example that uses methods defined on strings (where page.title is a string):

  1. {{ page.title.capitalize() }}

This also works for methods on user-defined types.For example, if variable f of type Foo has a method bar defined on it,you can do the following:

  1. {{ f.bar() }}