Blogg.se Template documentation

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.

Example usage

<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.


Statement delimiters

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.


Variables

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.


Filters

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.


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: disabled template because we no longer use this
    {% for comment in comments %}
        ...
    {% endfor %}
#}


Control Structures

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.


For

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

The if statement in Jinja is comparable with the if statements of Python. In the simplest form you can use it to test if a variable is defined, not empty or not false:
{% 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 %}

Kommentera