Jinja is a fast, expressive, extensible templating engine. Special placeholders in the template allow writing code similar to [Python](../dev/programming/languages/Python.md) syntax. Then the template is passed data to render the final document. Jinja template files commonly have the `.j2` extension.
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:
Jinja allows basic expressions everywhere. These work very similarly to regular [Python](../dev/programming/languages/Python.md); even if you’re not working with [Python](../dev/programming/languages/Python.md) you should feel comfortable with it.
The simplest form of expressions are literals. Literals are representations for [Python](../dev/programming/languages/Python.md) objects such as strings and numbers. The following literals exist:
Everything between two double or single quotes is a string. They are useful whenever you need a string in the template (e.g. as arguments to function calls and filters, or just to extend or include a template).
Floating point numbers can be written using a ‘.’ as a decimal mark. They can also be written in scientific notation with an upper or lower case ‘e’ to indicate the exponent part. The ‘_’ character can be used to separate groups for legibility, but cannot be used in the exponent part.
Everything between two brackets is a list. Lists are useful for storing sequential data to be iterated over. For example, you can easily create a list of links using lists and tuples for (and with) a for loop:
```
<ul>
{% for href, caption in [('index.html', 'Index'), ('about.html', 'About'),
Tuples are like lists that cannot be modified (“immutable”). If a tuple only 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.
A dict in [Python](../dev/programming/languages/Python.md) is a structure that combines keys and values. Keys must be unique and always have exactly one value. Dicts are rarely used in templates; they are useful in some rare cases such as the `xmlattr()` filter.
It is also possible to use inline if expressions. These are useful in some situations. For example, you can use this to extend from one template if a variable is defined, otherwise from the default layout template:
The else part is optional. If not provided, the else block implicitly evaluates into an `Undefined` object (regardless of what `undefined` in the environment is set to):
A filter that batches items. It works pretty much like slice just the other way round. It returns a list of lists with the given number of items. If you provide a second parameter this is used to fill up missing items. See this example:
This will output the value of `my_variable` if the variable was defined, otherwise `'my_variable is not defined'`. If you want to use default with variables that evaluate to false you have to set the second parameter to true:
Sort a dict and yield (key, value) pairs. [Python](../dev/programming/languages/Python.md) dicts may not be in the order you want to display them in, so sort them first.
Replace the characters `&`, `<`, `>`, `'`, and `"` in the string with HTML-safe sequences. Use this if you need to display text that might contain such characters in [HTML](../internet/HTML.md).
Format the value like a ‘human-readable’ file size (i.e. 13 kB, 4.1 MB, 102 Bytes, etc). Per default decimal prefixes are used (Mega, Giga, etc.), if the second parameter is set to True the binary prefixes are used (Mebi, Gibi).
Convert the value into a floating point number. If the conversion doesn’t work it will return `0.0`. You can override this default using the first parameter.
Group a sequence of objects by an attribute using [Python](../dev/programming/languages/Python.md)’s `itertools.groupby()`. The attribute can use dot notation for nested access, like `"address.city"`. Unlike [Python](../dev/programming/languages/Python.md)’s `groupby`, the values are sorted first so only one group is returned for each unique value.
For example, a list of `User` objects with a `city` attribute can be rendered in groups. In this example, `grouper` refers to the `city` value of the group.
`groupby` yields namedtuples of `(grouper, list)`, which can be used instead of the tuple unpacking above. `grouper` is the value of the attribute, and `list` is the items with that value.
This filter is useful if you expect the template to be rendered with an implementation of Jinja in another programming language that does not have a `.items()` method on its mapping type.
Return a string which is the concatenation of the strings in the sequence. The separator between elements is an empty string per default, you can define it with the optional parameter:
Return a copy of the value with all occurrences of a substring replaced with a new one. The first argument is the substring that should be replaced, the second is the replacement string. If the optional third argument `count` is given, only the first `count` occurrences are replaced:
Return a truncated copy of the string. The length is specified with the first parameter which defaults to `255`. If the second parameter is `true` the filter will cut the text at length. Otherwise it will discard the last word. If the text was in fact truncated it will append an ellipsis sign (`"..."`). If you want a different ellipsis sign than `"..."` you can specify it using the third parameter. Strings that only exceed the length by the tolerance margin given in the fourth parameter will not be truncated.
Quote data for use in a URL path or query using UTF-8.
Basic wrapper around urllib.parse.quote() when given a string, or urllib.parse.urlencode() for a dict or iterable.
##### urlize(value)
Convert URLs in text into clickable links.
This may not recognize links in some situations. Usually, a more comprehensive formatter, such as a [Markdown](../files/Markdown.md) library, is a better choice.
The if statement in Jinja is comparable with the [Python](../dev/programming/languages/Python.md) if statement. In the simplest form, you can use it to test if a variable is defined, not empty and not false:
