Get Django Updates

Jinja built-in filters and tests (like Django filters)

The Jinja documentation makes an explicit difference between what it calls filters and tests. The only difference is Jinja tests are used to evaluate conditions and Jinja filters are used to format or transform values. In Django there is no such naming difference and an equivalent Jinja test in Django is simply called a Django filter.

The syntax to apply Jinja filters to template variables is the vertical bar character | , also called a 'pipe' in Unix environments (e.g.{{variable|filter}}). It's worth mentioning you can apply multiple filters to the same variable (e.g.{{variable|filter|filter}}). The syntax to apply Jinja tests uses the is keyword along with a regular conditional to evaluate the validity of a test (e.g. {% if variable is divisibleby 10 %}do something{% endif %}).

In the upcoming sections, I'll add the reference (Test) to indicate it's referring to a Jinja test vs. a Jinja filter. I'll also classify each Django built-in filter & test into functional sections so they are easier to identify. I'll define the broadest category 'Strings, lists, dictionaries, numbers and objects' for filters and tests that pplicable for most scenarios and then more specialized sections for each data type, including: 'String and lists', 'Dictionaries and objects', Strings, Numbers, Spacing and special characters, Development and testing and Urls.

Strings, lists, dictionaries, numbers and objects

default or d.- The default or d filter is used to specify a default value if a variable is undefined or is false (i.e. it doesn't exist or is empty). For example, the filter statement {{variable|default("no value")}} outputs no value only if the variable is undefined, otherwise it outputs the variable value. If in addition you want to provide a default value for a variable that evaluates to false, is None or is an empty string, you have to add true as a second filter parameter (e.g. {{variable|default("no value",true)}} outputs no value if the variable is undefined, false, is None or is an empty string).

defined (Test).- The defined test is used to check if a variable is defined, if a variable is defined this tests return true. Listing 4-19 illustrates an example of the defined test.

Listing 4-19 Jinja defined test

{% if variable is defined %}
    value of variable: {{ variable }}
{% else %}
    variable is not defined
{% endif %}

none (Test).- The none test is used to check if a variable is none, if a variable is None this tests return true.

length or count.- The length filter is used to obtain the length of a value. For example, if a variable contains latte the filter statement {{variable|length}} outputs 5. For a list variable that contains ['a','e','i'] the filter statement {{variable|length}} outputs 3.

equalto (Test).- The equalto test checks if an object has the same value as another object. For example {% if coffee.price is equalto 1.99 %} coffee prices equals 1.99 {% endif %}. This works just like the ==, but is more helpful when used with other filters such as selectattr (e.g. {{ users|selectattr("email", "equalto", "webmaster@coffeehouse.com") }}, gets users with email webmaster@coffeehouse.com).

string (Test).- The string test checks if a variable is a string (e.g. {% if variable is string %}Yes, the variable is a string!{% endif %}).

number (Test).- The number test returns true if a variable is a number.

iterable (Test).- The iterable test checks if it's possible to iterate over an object.

sequence (Test).- The sequence test checks if the object is a sequence (e.g. a generator).

mapping (Test).- The mapping test checks if the object is a mapping (e.g. a dictionary).

callable (Test).- The callable test verifies if an object is callable. In Python a function, classes and object instances with a __call__ method are callables.

sameas (Test).- The sameas test verifies if an object points to the same memory address than another object.

Strings and lists

reverse.- The reverse filter is used to get inverse representation of a value. For example, if a variable contains latte the filter statement {{variable|reverse}} generates ettal.

first.- The first filter returns the first item in a list or string. For example, for a list variable that contains ['a','e','i','o','u'] the filter statement {{variable|first}} outputs a.

join.- The join filter joins a list with a string. The join filter works just like Python's str.join(list). For example, for a list variable that contains ['a','e','i','o','u'] the filter statement {{variable|join("--)}} outputs a--e--i--o--u. The join filter also supports joining certain attributes of an object (e.g.{{ users|join(', ', attribute='username') }})

last.- The last filter returns the last item in a list or string. For example, for a list variable that contains ['a','e','i','o','u'] the filter statement {{variable|last}} outputs u.

map.- The map filter allows you to apply a filter or look up attributes, just like the standard Python map method. For example, if you have list of users but are only interested in outputting a list of usernames a map is helpful (e.g. {{ users|map(attribute='username')|join(', ') }}). In addition, it's also possible to invoke a filter by passing the name of the filter and the arguments afterwards (e.g. {{ titles|map('lower')|join(', ') }} applies the lower filter to all the elements in titles and then joins the items separated by a comma).

random.- The random filter returns a random item in a list. For example, for a list variable that contains ['a','e','i','o','u'] the filter statement {{variable|random}} could output a, e, i, o or u.

reject.- The reject filter removes elements that pass a certain test -- see bullets in this chapter section marked as (Test) for acceptable values. For example, for a list variable that contains [1,2,3,4,5] the loop statement with this filter {% for var in variable|reject("odd") %}{{var}}{% endfor %} -- where odd is the Jinja test -- rejects elements that are odd and thus its output is 2 and 4.

select.- The select filter selects elements that pass a certain test -- see bullets in this chapter section marked as (Test) for acceptable values. For example, for a list variable that contains [1,2,3,4,5] the loop statement with this filter {% for var in variable|select("odd") %}{{var}}{% endfor %} -- where odd is the Jinja test -- selects elements that are odd and thus its output is 1, 3 and 5.

slice.- The slice filter returns a slice of lists. For example, for a variable that contains ["Capuccino"] the filter statement {% for var in variable|slice(4) %}{{var}}{% endfor %} outputs ['C', 'a', 'p'],['u', 'c'],['c', 'i'], ['n', 'o']. It's possible to use the fill_with as a second argument -- which defaults to None -- so all segments contain the same number of elements filled with a given value. For example, {% for var in variable|slice(4,'FILLER') %}{{var}}{% endfor %} outputs: ['C', 'a', 'p'],['u', 'c','FILLER'],['c', 'i','FILLER'], ['n', 'o','FILLER'].

batch.- The batch filter returns a batch of lists. For example, a variable that contains ["Capuccino"] the filter statement {% for var in variable|batch(4) %}{{var}}{% endfor %} outputs ['C', 'a', 'p', 'u'],['c', 'c', 'i', 'n'],['o']. It's possible to use the fill_with as a second argument -- which defaults to None -- so all segments contain the same number of elements filled with a given value. For example, {% for var in variable|slice(4,'FILLER') %}{{var}}{% endfor %} outputs: ['C', 'a', 'p', 'u'],['c', 'c', 'i', 'n'],['o','FILLER','FILLER','FILLER'].

sort.- The sort filter sorts elements by ascending order. For example, if a variable contains ['e','u','a','i','o'] the statement {{variable|sort}} outputs ['a','e','i','o','u']. It's possible to indicate descending order by setting the first argument to true (e.g. {{variable|sort(true)}} outputs ['u','o','i','e','a']). In addition, if a list is made up strings, a second argument can be used to indicate case sensitiveness -- which is disabled by default -- to perform the sort operation (e.g. {{variable|sort(true,true)}}). Finally, if a list is composed of objects, it's also possible to specify the sort operation on a given attribute (e.g. variable|sort(attribute='date') to sort the elements based on the date attribute).

Dictionaries and objects

dictsort.- The dictsort filter sorts a dictionary by key, case insensitive. For example, if a variable contains {'name':'Downtown','city':'San Diego','state':'CA'} the filter {% with newdict=variable|dictsort %} the newdict variable is assigned the dictionary {'city':'San Diego','name':'Downtown','state':'CA'}. In addition, the dictsort can accept two arguments, for case sensitive/insensitive order and sorting by key/value. The default behavior is case insensitive sort by key (e.g. variable|dictsort), to use case sensitive sort by key use true as the first argument (e.g.variable|dictsort(true)), to use sort by value is value as the second argument (e.g.variable|dictsort(false,'value') performs a case insensitive sort by value).

attr.- The attr filter returns the attribute of an object (e.g. {{coffeehouse.city}} outputs the city attribute value of the coffeehouse object). Note the attr filter only attempts to look up an attribute and not an item (e.g. if coffeehouse is a dictionary and city is a key item it won't be found). Alternatively, you can just use the standard Python syntax variable.name -- which first attempts to locate an attribute called name on variable, then the name item on variable or if nothing matches an undefined object is returned -- or variable['name'] -- which first attempts to locate the name item on variable, then an attribute called name on variable or if nothing matches an undefined object is returned.

rejectattr.- The rejectattr filter removes objects that don't contain an attribute or objects for which a certain attribute doesn't pass a test -- see bullets in this chapter section marked as (Test) for acceptable values. For example, {% for ch in coffeehouses|rejectattr("closedon") %} generates a loop for coffeehouse objects that don't have the closedon attribute or {% for u in users|rejectattr("email", "none") %} generates a loop for user objects that don't have email None -- note the second argument none represents the test.

selectattr.- The selectattr filter selects objects that contain an attribute or objects for which a certain attribute passes a test -- see bullets in this chapter section marked as (Test) for acceptable values. For example, {% for u in users|selectattr("superuser") %} generates a loop for user objects that have the superuser attribute or {% for u in users|selectattr("email", "none") %} generates a loop for user objects that have email None -- note the second argument none represents the test.

groupby.- The groupby filter is used to rearrange the contents of a list of dictionaries or objects into different group object sequences by a common attribute. Listing 4-20 illustrates an example of the groupby filter.

Listing 4-20. Jinja groupby filter

# Dictionary definition
stores = [
    {'name': 'Downtown', 'street': '385 Main Street', 'city': 'San Diego'},
    {'name': 'Uptown', 'street': '231 Highland Avenue', 'city': 'San Diego'},
    {'name': 'Midtown', 'street': '85 Balboa Street', 'city': 'San Diego'},
    {'name': 'Downtown', 'street': '639 Spring Street', 'city': 'Los Angeles'},
    {'name': 'Midtown', 'street': '1407 Broadway Street', 'city': 'Los Angeles'},
    {'name': 'Downton', 'street': '50 1st Street', 'city': 'San Francisco'},
]
<ul>
{% for group in stores|groupby('city') %}
    <li>{{ group.grouper }}
    <ul>
        {% for item in group.list %}
          <li>{{ item.name }}: {{ item.street }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>
# Output
Los Angeles
    Downtown: 639 Spring Street
    Midtown: 1407 Broadway Street
San Diego
    Downtown : 385 Main Street
    Uptown : 231 Highland Avenue
    Midtown : 85 Balboa Street
San Francisco
    Downtown: 50 1st Street
# Alternate shortcut syntax, produces same output
<ul>
{% for grouper, list in stores|groupby('city') %}
    <li>{{ grouper }}
    <ul>
        {% for item in list %}
          <li>{{ item.name }}: {{ item.street }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

tojson.- The tojson filter outputs data structures to JavaScript Object Notation(JSON) (e.g.{{variable|tojson}}). The tojson filter accepts the indent argument -- which is set to None -- to generate pretty output by a given number of spaces (e.g. {{variable|tojson(indent=2)}}) generates output indented with two spaces).

Tip You can globally set options for the tojson filter through Jinja policies, described in the last section of this chapter.

Strings

capitalize.- The capitalize filter capitalizes the first character of a string variable. For example, if a variable contains hello world the filter statement {{variable|capitalize}} outputs Hello world.

list.- The list filter is used to return a list of characters. For example, if a variable contains latte the filter statement {{variable|list}} generates ['l','a','t','t','e'].

lower.- The lower filter converts all values of a string variable to lowercase. For example, if a variable contains Hello World the filter statement {{variable|lower}} outputs hello world.

lower (Test).- The lower test returns true if a variable is lower cased. For example, {% if variable is lower %}Yes, the variable is lowercase!{% endif %} outputs the statement if variable is lower cased

replace.- The replace filter works just like Python's standard replace string. The first argument is the sub-string that should be replaced, the second is the replacement string. If the optional third argument amount is given, only this amount of occurrences are replaced. For example {{ "Django 1.8"|replace("1.8", "1.9") }} outputs Django 1.9 and {{"oooh Django!"|replace("o", "",2) }} outputs oh Django!.

string.- The string filter makes a string unicode if it isn't already.

title.- The title filter converts all first character values of a string variable to uppercase. For example, if a variable contains hello world the filter statement {{variable|title}} outputs Hello World.

upper.- The upper filter converts all values of a string variable to uppercase. For example, if a variable contains Hello World the filter statement {{variable|upper}} outputs HELLO WORLD.

upper (Test).- The upper test returns true if a variable is upper cased. For example, {% if variable is upper %}Yes, the variable is uppercase!{% endif %} outputs the statement if variable is uppercase.

wordcount.- The wordcount filter counts the words in a string. For example, if a variable contains Coffeehouse started as a small store the filter statement {{variable|wordcount}} outputs 6.

Numbers

abs.- The abs return the absolute value of the number argument. For example, if a variable contains -5 the filter statement {{variable|abs}} outputs 5.

filesizeformat.-The filesizeformat filter converts a number of bytes into a friendly file size string. For example, if a variable contains 250 the filter statement {{variable|filesizeformat}} outputs 250 Bytes, if it contains 2048 the output is 2 kB, if it contains 2000000000 the output is 2.0 GB. By default, decimal prefixes are used (e.g. Giga, Mega, Kilo), if you pass an additional boolean parameter with true (e.g. {{variable|filesizeformat(true)}}) then binary prefixes are used (e.g. Gibi, Mebi, Kibi)

float.- The float filter converts a value into a floating-point number. If the conversion doesn't work it returns 0.0 or a custom value argument (e.g. variable|float("It didn't work") returns "It didn't work" if variable can't be converted to a floating-point number).

int.- The int filter converts a value into an integer. If the conversion doesn't work it returns 0 or a custom value specified as the first argument to the filter -- just like the float filter. You can also override the default base 10 with a second filter argument, which handles input with prefixes such as 0b, 0o and 0x for bases 2, 8 and 16 respectively (e.g. {{'0b001111'|int(0,2)}} a base 2 number outputs 15.

round.- The round filter rounds a number to a given precision, where the first argument is the precision -- which defaults to 0 -- and the second argument is a rounding method -- which defaults to 'common' rounding either up or down. For example, {{ 33.55|round }} assumes 'common' rounding to output 34.0). In addition to 'common', it's also possible to use 'ceil' to always round up or 'floor' to always round down (e.g. {{ 33.55|round(1,'floor') }} outputs 33.5). Note that even if rounded to the default 0 precision, a float is returned. If you need an integer you can apply the int filter (e.g. {{ 33.55|round|int }} outputs 34).

sum.- The sum filter returns the sum of a sequence of numbers, plus the value provided with the start parameter which defaults to 0. In addition, it's also possible to sum certain attributes of a list of objects {{ items|sum(attribute='price') }}.

divisibleby (Test).- The divisibleby test checks if a variable is divisible by a given number. For example, if a variable contains 20 the filter statement {% if variable is divisibleby(5) %}Variable is divisible by 5!{% endif %} outputs the conditional statement.

even (Test).- The even test checks if a number is even.

odd (Test).- The odd test checks if a number is odd.

Spacing and special characters

center.- The center filter center aligns a value and pads it with additional white space characters until it reaches the given argument of characters. For example, if a variable contains mocha the filter statement {{variable|center(width="15")}} outputs " mocha ".

escape or e.- The escape or e filter escapes HTML characters from a value. Specifically with the escape filter: < is converted to &lt;,> is converted to &gt;,' (single quote) is converted to &#39;," (double quote) is converted to &quot;, and & is converted to &amp.

escaped (Test).- The escaped test checks if a value is escaped.

forceescape.- The forceescape filter escapes HTML characters from a value just like the escape filter. The difference between both filters is the forceescape filter is applied immediately and returns a new and escaped string. This is useful in the rare cases where you need multiple escaping or want to apply other filters to the escaped results. Normally, you'll use the escape filter.

format.- The format filter is used to apply Python string formatting to a variable. For example, the statement {{ "%s and %s"|format("Python", "Django!") }} outputs Python and Django!.

indent.- The indent filter is used to output a string with each line except the first one indented with four spaces. It's possible to change the number of spaces and the indentation of the first line with additional filter arguments (e.g. {{ textvariable|indent(2, true) }} the 2 indicates two spaces and true indicates to indent the first line.

safe.- The safe filter marks a string as not requiring further HTML escaping. When this filter is used with an environment without automatic escaping it has no effect.

striptags.- The striptags filter removes all HTML tags from a value. For example, if a variable contains <b>Coffee</b>house, the <i>best</i> <span>drinks</span> the filter statement {{variable|striptags}} outputs Coffeehouse, the best drinks.

trim.- The trim filter is used to strip leading and trailing whitespace just like Python's string strip() method.

truncate.- The truncate filter truncates a string to a given number of characters -- defaulting to 255 characters -- and appends an ellipsis sequence. For example, if a variable contains Coffeehouse started as a small store the filter statement {{variable|truncate(20)}} outputs Coffeehouse ..., keeping up until character number 20 and then discarding the last full word, finally adding the ellipsis. You can add true as a second argument so the string is cut at an exact length (e.g. {{variable|truncate(20,true)}} outputs Coffeehouse start... including the ellipsis characters). It's possible to provide a different symbol than an ellipsis passing a second parameter (e.g.{{variable|truncate(20,true,"!!!")}} would output !!! instead of an elipsis). And finally, the truncate filter accepts a fourth argument leeway to specify a string tolerance in characters -- which defaults to 5 -- to avoid truncating strings (e.g. this avoids truncating words with less than 5 characters).

Tip You can globally set the leeway value for the truncate filter through Jinja policies, described in the last section of this chapter.

wordwrap.- The wordwrap filter wraps words at a given character line length argument. By default, the wrapping occurs after 79 characters which can be overridden providing a first argument with the number of characters. If you set a second parameter to false, Jinja does not split words longer than the wrapping character length. In addition, wrapping generates a newline character as defined in the environment -- generally the \n character -- but this can be changed by specifying the wrapstring keyword argument (e.g. {{variable|wordwrap(40,true,'-') uses a hyphen as the wrapping newline character). Listing 4-21 illustrates an example of the wordwrap filter.

Listing 4-21. Jinja wordwrap filter

# Variable definition 
Coffeehouse started as a small store
# Template definition with wordwrap filter for every 12 characters
{{variable|wordwrap(12)}}
# Output
Coffeehouse 
started as a
small store

xmlattr.- The xmlattr filter is used to create an SGML/XML attribute string based on the items in a dictionary or object. Once you create a dictionary structure containing attribute names and reference values, you pass it through the xmlattr filter to generate the attribute string. By default, all values that are neither none or undefined are automatically escaped, but you can override this behavior by passing false as the first filter argument. Listing 4-22 illustrates an example of the xmlattr filter.

Listing 4-22. Django xmlattr filter

# Variable definition 
{% set stores = [
    {'id':123,'name': 'Downtown', 'street': '385 Main Street', 'city': 'San Diego'},
    {'id':243,'name': 'Uptown', 'street': '231 Highland Avenue', 'city': 'San Diego'},
    {'id':357,'name': 'Midtown', 'street': '85 Balboa Street', 'city': 'San Diego'},
    {'id':478,'name': 'Downtown', 'street': '639 Spring Street', 'city': 'Los Angeles'},
    {'id':529,'name': 'Midtown', 'street': '1407 Broadway Street', 'city': 'Los Angeles'},
    {'id':653,'name': 'Downton', 'street': '50 1st Street', 'city': 'San Francisco'},
] %}
# Template definition
<ul>
{% for store in stores %}
  <li {{ {'id':'%d'|format(store.id),'class':'%s'|format(store.city|lower|replace(' ','-')) }|xmlattr }}> {{store.city}} {{store.name}}</li>
{% endfor %}
</ul>
# Output
<ul>
  <li id="123" class="san-diego"> San Diego Downtown</li>
  <li id="243" class="san-diego"> San Diego Uptown</li>
  <li id="357" class="san-diego"> San Diego Midtown</li>
  <li id="478" class="los-angeles"> Los Angeles Downtown</li>
  <li id="529" class="los-angeles"> Los Angeles Midtown</li>
  <li id="653" class="san-francisco"> San Francisco Downton</li>
</ul>

Development and testing

pprint.- The pprint filter is a wrapper for Python's pprint.pprint(). The pprint filter is useful during development and testing because it outputs the formatted representation of an object. By default, the pprint filter is not verbose but you can make it verbose passing it the true argument (e.g. {{variable|pprint(true)}}).

Urls

urlencode.- The urlencode filter escapes a value for use in a URL. For example, if a variable contains http://localhost/drinks?type=cold&size=large the filter statement {{variable|urlencode}} outputs http%3A//localhost/drinks%3Ftype%3Dcold%26size%3Dlarge.

urlize.- The urlize filter converts text URLs into clickable HTML links. You can pass the filter an additional integer to shorten the visible url (e.g. {{ variable|urlize(40)}} links are shortened to 40 characters plus an ellipsis). It's also possible to add a second argument as a boolean to make the urls "nofollow" (e.g. {{ variable|urlize(40, true)}} links are shortened to 40 characters and defined with rel="nofollow"). Finally, it's also possible to add the target argument to define a link target (e.g.{{ variable|urlize(40, target="_blank")}} links are shortened to 40 characters and open in a new window).

Tip You can globally set rel and target values for the the urlize filter through Jinja policies, described in the last section of this chapter.