kevin-brown/control-structures.md

Last active May 20, 2024 20:19

Star (0) You must be signed in to star a gist
Fork (0) You must be signed in to fork a gist

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/kevin-brown/ec945b60024d35ed9c09ec70142af7fe.js"></script>
Save kevin-brown/ec945b60024d35ed9c09ec70142af7fe to your computer and use it in GitHub Desktop.

Download ZIP

Examples of syntax for the Jinja templating language

Raw

control-structures.md

for

Basic with list

<h1>Members</h1>
<ul>
{% for user in users %}
  <li>{{ user.username|e }}</li>
{% endfor %}
</ul>

Basic with dictionary

<dl>
{% for key, value in my_dict.items() %}
    <dt>{{ key|e }}</dt>
    <dd>{{ value|e }}</dd>
{% endfor %}
</dl>

loop.cycle()

{% for row in rows %}
    <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
{% endfor %}

For loop with conditional

{% for user in users if not user.hidden %}
    <li>{{ user.username|e }}</li>
{% endfor %}

For loop with else

<ul>
{% for user in users %}
    <li>{{ user.username|e }}</li>
{% else %}
    <li><em>no users found</em></li>
{% endfor %}
</ul>

Recursive for loop

<ul class="sitemap">
{%- for item in sitemap recursive %}
    <li><a href="{{ item.href|e }}">{{ item.title }}</a>
    {%- if item.children -%}
        <ul class="submenu">{{ loop(item.children) }}</ul>
    {%- endif %}</li>
{%- endfor %}
</ul>

loop.previtem and loop.nextitem

{% for value in values %}
    {% if loop.previtem is defined and value > loop.previtem %}
        The value just increased!
    {% endif %}
    {{ value }}
    {% if loop.nextitem is defined and loop.nextitem > value %}
        The value will increase even more!
    {% endif %}
{% endfor %}

loop.changed()

{% for entry in entries %}
    {% if loop.changed(entry.category) %}
        <h2>{{ entry.category }}</h2>
    {% endif %}
    <p>{{ entry.message }}</p>
{% endfor %}

if

Basic usage

{% if users %}
<ul>
{% for user in users %}
    <li>{{ user.username|e }}</li>
{% endfor %}
</ul>
{% endif %}

elif and else

{% if kenny.sick %}
    Kenny is sick.
{% elif kenny.dead %}
    You killed Kenny!  You bastard!!!
{% else %}
    Kenny looks okay --- so far
{% endif %}

macro

{% macro input(name, value='', type='text', size=20) -%}
    <input type="{{ type }}" name="{{ name }}" value="{{
        value|e }}" size="{{ size }}">
{%- endmacro %}

{% macro input(name, value='', type='text') -%}
    <input type="{{ type }}" value="{{ value|e }}" name="{{ name }}">
{%- endmacro %}

{%- macro textarea(name, value='', rows=10, cols=40) -%}
    <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols
        }}">{{ value|e }}</textarea>
{%- endmacro %}

call

{% macro render_dialog(title, class='dialog') -%}
    <div class="{{ class }}">
        <h2>{{ title }}</h2>
        <div class="contents">
            {{ caller() }}
        </div>
    </div>
{%- endmacro %}

{% call render_dialog('Hello World') %}
    This is a simple dialog rendered by using a macro and
    a call block.
{% endcall %}

Returning values

{% macro dump_users(users) -%}
    <ul>
    {%- for user in users %}
        <li><p>{{ user.username|e }}</p>{{ caller(user) }}</li>
    {%- endfor %}
    </ul>
{%- endmacro %}

{% call(user) dump_users(list_of_user) %}
    <dl>
        <dt>Realname</dt>
        <dd>{{ user.realname|e }}</dd>
        <dt>Description</dt>
        <dd>{{ user.description }}</dd>
    </dl>
{% endcall %}

filter

Basic

{% filter upper %}
    This text becomes uppercase
{% endfilter %}

Arguments

{% filter center(100) %}Center this{% endfilter %}

set

Single assignment

{% set navigation = [('index.html', 'Index'), ('about.html', 'About')] %}

Multiple assignment

{% set key, value = call_something() %}

Namespaces

{% set ns = namespace(found=false) %}
{% for item in items %}
    {% if item.check_something() %}
        {% set ns.found = true %}
    {% endif %}
    * {{ item.title }}
{% endfor %}
Found item having something: {{ ns.found }}

Block assignment

{% set navigation %}
    <li><a href="/">Index</a>
    <li><a href="/downloads">Downloads</a>
{% endset %}

Block assignment with filters

{% set reply | wordwrap %}
    You wrote:
    {{ message }}
{% endset %}

include

Basic

{% include 'header.html' %}
Body goes here.
{% include 'footer.html' %}

With context

{% include "sidebar.html" without context %}

Ignore missing

{% include "sidebar.html" ignore missing %}

Ignore missing with context

{% include "sidebar.html" ignore missing with context %}

Ignore missing without context

{% include "sidebar.html" ignore missing without context %}

List of templates

{% include ['page_detailed.html', 'page.html'] %}

List of templates ignore missing

{% include ['special_sidebar.html', 'sidebar.html'] ignore missing %}

Template as a variable

{% include template_name %}

import / from

Basic as

{% import 'forms.html' as forms %}

From import

{% from 'forms.html' import input as input_field, textarea %}

From import with context

{% from 'forms.html' import input with context %}

block

<!DOCTYPE html>
<html lang="en">
<head>
    {% block head %}
    <link rel="stylesheet" href="style.css" />
    <title>{% block title %}{% endblock %} - My Webpage</title>
    {% endblock %}
</head>
<body>
    <div id="content">{% block content %}{% endblock %}</div>
    <div id="footer">
        {% block footer %}
        &copy; Copyright 2008 by <a href="http://domain.invalid/">you</a>.
        {% endblock %}
    </div>
</body>
</html>

Super usage

{% block sidebar %}
    <h3>Table Of Contents</h3>
    ...
    {{ super() }}
{% endblock %}

Super super usage

{% block body %}Hi from grandchild2. {{ super.super() }} {% endblock %}

Named block end tags

{% block sidebar %}
    {% block inner_sidebar %}
        ...
    {% endblock inner_sidebar %}
{% endblock sidebar %}

Scoped block nesting

{% for item in seq %}
    <li>{% block loop_item scoped %}{{ item }}{% endblock %}</li>
{% endfor %}

Required blocks

{% block body required %}{% endblock %}

Scoped required blocks

{% block body scoped %}{% endblock %}
{% block body required %}{% endblock %}
{% block body scoped required %}{% endblock %}

extends

{% extends "base.html" %}

Raw

expressions.md

Literals

Strings

"Hello World"

Integers

Integers with underscores

123_456

Floats

42.23

Floats with exponential notation

42.1e2

Floats with underscores

123_456.789

List

['list', 'of', 'objects']

Tuple

('tuple', 'of', 'values')

Dictionary

{'dict': 'of', 'key': 'and', 'value': 'pairs'}

Constants

true

false

none

Math

Addition

{{ 1 + 1 }}

Subtraction

{{ 3 - 2 }}

Division

{{ 1 / 2 }}

Integer division

{{ 20 // 7 }}

Modulo divison

{{ 11 % 7 }}

Multiplication

{ 2 * 2 }}

{{ '=' * 80 }}

Power

{{ 2**3 }}

{{ 3**3**3 }}

Comparisons

Equals

a == b

Not equals

Greater than

a > b

Greater than or equal

a >= b

Less than

a < b

Less than or equal

a <= b

Logic

And

a and b

a or b

Not

not a

Parentheses

a and (b or c)

Other operators

{{ 1 in [1, 2, 3] }}

{{ 1 not in [2, 3] }}

Concatenation

{{ "Hello " ~ name ~ "!" }}

If expressions

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

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

Raw

filters.md

abs

foo|abs

attr

foo|attr("bar")

batch

<table>
{%- for row in items|batch(3, '&nbsp;') %}
  <tr>
  {%- for column in row %}
    <td>{{ column }}</td>
  {%- endfor %}
  </tr>
{%- endfor %}
</table>

capitalize

foo|capitalize

center

foo|center

foo|center(20)

default

Default if not defined

{{ my_variable|default('my_variable is not defined') }}

Default if false

{{ ''|default('the string was empty', true) }}

dictsort

Sort the dict by key, case insensitive

{% for key, value in mydict|dictsort %}
    sort the dict by key, case insensitive
{% endfor %}

Sort the dict by key, case insensitive, reverse order

{% for key, value in mydict|dictsort(reverse=true) %}
    sort the dict by key, case insensitive, reverse order
{% endfor %}

Sort the dict by key, case sensitive

{% for key, value in mydict|dictsort(true) %}
    sort the dict by key, case sensitive
{% endfor %}

Sort the dict by value, case insensitive

{% for key, value in mydict|dictsort(false, 'value') %}
    sort the dict by value, case insensitive
{% endfor %}

escape

foo|escape

filesizeformat

Decimal prefixes

foo|filesizeformat

Binary prefixes

foo|filesizeformat(false)

first

foo|first

float

No default

foo|float

With default

foo|float(1.0)

forceescape

foo|forceescape

format

{{ "%s, %s!"|format(greeting, name) }}
Hello, World!

groupby

Attribute retrieval with unpacking

<ul>{% for city, items in users|groupby("city") %}
  <li>{{ city }}
    <ul>{% for user in items %}
      <li>{{ user.name }}
    {% endfor %}</ul>
  </li>
{% endfor %}</ul>

Without unpacking

<ul>{% for group in users|groupby("city") %}
  <li>{{ group.grouper }}: {{ group.list|join(", ") }}
{% endfor %}</ul>

Default for missing attribute

<ul>{% for city, items in users|groupby("city", default="NY") %}
  <li>{{ city }}: {{ items|map(attribute="name")|join(", ") }}</li>
{% endfor %}</ul>

Case insensitive grouping

<ul>{% for group in users|groupby("city", case_sensitive=True) %}
  <li>{{ group.grouper }}: {{ group.list|join(", ") }}
{% endfor %}</ul>

indent

Default indent 4

foo|indent

Indent the first line as well

foo|indent(first=True)

Indent blank lines as well

foo|indent(blank=True)

int

Standard usage

foo|int

Default if failed to convert

foo|int(100)

Base for conversion

foo|int(base=2)

items

<dl>
{% for key, value in my_dict|items %}
    <dt>{{ key }}
    <dd>{{ value }}
{% endfor %}
</dl>

join

Implicit join with no separator

{{ [1, 2, 3]|join }}

Join separator

{{ [1, 2, 3]|join('|')

Join attributes

{{ users|join(', ', attribute='username') }}

last

{{ data | selectattr('name', '==', 'Jinja') | list | last }}

length

foo|length

foo|count

list

foo|list

lower

foo|lower

map

Attribute lookup

Users on this page: {{ users|map(attribute='username')|join(', ') }}

Attribute with default

{{ users|map(attribute="username", default="Anonymous")|join(", ") }}

Mapping function

Users on this page: {{ titles|map('lower')|join(', ') }}

max / min

Default usage

[1, 2, 3]|min

Case sensitive

['a', 'A', 'b', 'B']|min(case_sensitive=False)

Attribute comparison

foo|min(attribute="bar")

pprint

foo|pprint

random

[1, 2, 3]|random

reject

Reject as boolean

{{ [True, False, True]|reject }}

Reject with a test

{{ numbers|reject("odd") }}

rejectattr

Boolean on atttribute

{{ users|rejectattr("is_active") }}

Test applied to attribute

{{ users|rejectattr("email", "none") }}

replace

Standard find and replace

{{ "Hello World"|replace("Hello", "Goodbye") }}

Only replace a certain number of occurrences

{{ "aaaaargh"|replace("a", "d'oh, ", 2) }}

reverse

[1, 2, 3]|reverse

round

Default common integrer rounding

{{ 42.55|round }}

Specify the rounding precision

{{ 42.55|round(1) }}

Specify the rounding method

{{ 42.55|round(1, 'floor') }}

safe

foo|safe

select

Selecting by truthiness

{{ [True, False, True]|select }}

Calling a standard test

{{ numbers|select("odd") }}

Calling a test with a parameter

{{ numbers|select("divisibleby", 3) }}

{{ numbers|select("lessthan", 42) }}

{{ strings|select("equalto", "mystring") }}

selectattr

Boolean on atttribute

{{ users|selectattr("is_active") }}

Test applied to attribute

{{ users|selectattr("email", "none") }}

slice

Slicing specific number

<div class="columnwrapper">
  {%- for column in items|slice(3) %}
    <ul class="column-{{ loop.index }}">
    {%- for item in column %}
      <li>{{ item }}</li>
    {%- endfor %}
    </ul>
  {%- endfor %}
</div>

Filling missing slices

<div class="columnwrapper">
  {%- for column in items|slice(3, 'TBD') %}
    <ul class="column-{{ loop.index }}">
    {%- for item in column %}
      <li>{{ item }}</li>
    {%- endfor %}
    </ul>
  {%- endfor %}
</div>

sort

Built-in sorted

{% for city in cities|sort %}
    ...
{% endfor %}

Reverse sorting

{% for user in users|sort(attribute="name")
    |sort(reverse=true, attribute="age") %}
    ...
{% endfor %}

Sorting by attribute

{% for user in users|sort(attribute="age,name") %}
    ...
{% endfor %}

string

foo|string

striptags

foo|striptags

sum

Standard sum

Total: {{ items|sum }}

Starting value

([1,2],[3,4])|sort(start=[])

Sum by attribute

Total: {{ items|sum(attribute='price') }}

title

foo|title

tojson

Compressed JSON

foo|tojson

Indenting a certain number

foo|tojson(4)

trim

Trim whitespace

foo|trim

Trim specific characters

foo|trim('abc')

truncate

Truncate after a certain number of characters

{{ "foo bar baz qux"|truncate(9) }}

{{ "foo bar baz qux"|truncate(11) }}

Specify if truncating in the middle of a word is allowed

{{ "foo bar baz qux"|truncate(9, True) }}

Specify a custom string to use for the ellipsis sign

{{ "foo bar baz qux"|truncate(9, False, '---') }}

Specify the amount of leeway when truncating

{{ "foo bar baz qux"|truncate(11, leeway=0) }}

unique

{{ ['foo', 'bar', 'foobar', 'FooBar']|unique }}

{{ ['foo', 'bar', 'foobar', 'FooBar']|unique(case_sensitive=True) }}

{{ ['foo', 'bar', 'foobar', 'FooBar']|unique(attribute='upper', case_sensitive=True) }}

upper

foo|upper

urlencode

foo|urlencode

urlize

foo|urlize

foo|urlize(trim_url_limit=50)

foo|urlize(nofollow=True)

foo|urlize(target='_blank')

foo|urlize(rel='nofollow')

foo|urlize(extra_schemes=['mock'])

wordcount

foo|wordcount

wordwrap

foo|wordwrap(120)

foo|wordwrap(break_long_words=True)

foo|wordwrap(break_on_hyphens=True)

foo|wordwrap(wrapstring='<br />')

xmlattr

<ul{{ {'class': 'my_list', 'missing': none,
        'id': 'list-%d'|format(variable)}|xmlattr }}>
...
</ul>