The template engine that blogg.se uses is called Jinja, and complete documentation can be found at http://jinja.pocoo.org/docs/templates/. In the blog templates, Jinja is used primarily to render variables and for loops. The newer themes also use inheritance, reducing the amount of code in each template.
<ul>
{% for category in categories %}
<li><a href="{{ category.url }}">{{ category.name }}</a></li>
{% endfor %}
</ul>
In the example above, the variable categories is an array containing all categories for the blog. The example loops through all categories and renders each one as a link in a list.
Note that each category in the list is an object, containing the attributes name and url,which is an absolute path to the category page.
There are two kinds of delimiters. {% ... %} and {{ ... }}. The first one is used to execute statements such as for-loops or assign values, the latter prints the result of the expression to the template.
You can use a dot (.) to access attributes of a variable, alternative the so-called “subscript” syntax ([]) can be used. The following lines do the same:
{{ foo.bar }}
{{ foo['bar'] }}
It’s important to know that the curly braces are not part of the variable but the print statement. If you access variables inside tags don’t put the braces around.
If a variable or attribute does not exist you will get back an undefined value.
Variables can be modified by filters. Filters are separated from the variable by a pipe symbol (|) and may have optional arguments in parentheses. Multiple filters can be chained. The output of one filter is applied to the next.
{{ name|striptags|title }} for example will remove all HTML Tags from the name and title-cases it. Filters that accept arguments have parentheses around the arguments, like a function call. This example will join a list by commas: {{ list|join(', ') }}.
For a complete list of available filters, please see the the Jinja documentation.
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: disabled template because we no longer use this
{% for comment in comments %}
...
{% endfor %}
#}
A control structure refers to all those things that control the flow of a program - conditionals (i.e. if/elif/else), for-loops, as well as things like macros and blocks. Control structures appear inside {% ... %} blocks in the default syntax.
Loop over each item in a sequence. For example, to display a list of users provided in a variable called users:
<h1>Entries</h1>
<ul>
{% for entry in entries %}
<li>{{ entry.title|e }}</li>
{% endfor %}
</ul>
Inside of a for-loop block you can access some special variables:
| Variable | Description |
|---|---|
| loop.index | The current iteration of the loop. (1 indexed) |
| loop.index0 | The current iteration of the loop. (0 indexed) |
| loop.revindex | The number of iterations from the end of the loop (1 indexed) |
| loop.revindex0 | The number of iterations from the end of the loop (0 indexed) |
| loop.first | True if first iteration. |
| loop.last | True if last iteration. |
| loop.length | The number of items in the sequence. |
| loop.cycle | A helper function to cycle between a list of sequences. See the explanation below. |
Within a for-loop, it’s possible to cycle among a list of strings/variables each time through the loop by using the special loop.cycle helper:
{% for row in rows %}
<li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
{% endfor %}
{% if entries %}
<ul>
{% for entry in entries %}
<li>{{ entry.title|e }}</li>
{% endfor %}
</ul>
{% endif %}
For multiple branches elif and else can be used. You can use more complex Expressions there too:
{% if entry.comment_count > 1 %}
The entry has more than one comment!
{% elif entry.comment_count %}
The entry has one comment.
{% else %}
No comments :(
{% endif %}