Filters

Overview

You can modify variables for display by using filters.

Filters look like this: {{ name|lower }}. This displays the value of the {{ name }} variable after being filtered through the lower filter, which converts text to lowercase. Use a pipe (|) to apply a filter.

Filters can be “chained.” The output of one filter is applied to the next. {{ text|escape|linebreaks }} is a common idiom for escaping text contents, then converting line breaks to <p> tags.

Some filters take arguments. A filter argument looks like this: {{ bio|truncatewords:30 }}. This will display the first 30 words of the bio variable.

Filter arguments that contain spaces must be quoted; for example, to join a list with commas and spaced you’d use {{ list|join:", " }}.

Djula provides about thirty built-in template filters. You can read all about them in the built-in filter reference. To give you a taste of what’s available, here are some of the more commonly used template filters:

List of filters

add

Adds the argument to the value.

For example:

{{ value|add "2" }}

If value is 4, then the output will be 6.

addslashes

Adds slashes before quotes. Useful for escaping strings in CSV, for example.

For example:

{{ value|addslashes }}

If value is "I'm using Djula", the output will be "I\'m using Djula".

capfirst

Capitalizes the first character of the value. If the first character is not a letter, this filter has no effect.

For example:

{{ value|capfirst }}

If value is "djula", the output will be "Djula".

cut

Removes all values of arg from the given string.

For example:

{{ value|cut:" " }}

If value is "String with spaces", the output will be "Stringwithspaces".

date

Formats a date

Example::
{{ date-today | date }}

A LOCAL-TIME format spec can be provided:

{{ date-today | date ()

time

Formats a time

Example:

{{ time-now | time }}

datetime

Formats a date and time

Example:

{{ time-now | datetime }}

default

If value evaluates to False, uses the given default. Otherwise, uses the value.

For example:

{{ value|default "nothing" }}

If value is "" (the empty string), the output will be nothing.

sort

Takes a list and returns that list sorted.

For example:

{{ list | sort }}

reverse

Takes a list and returns that list reversed.

For example:

{{ list | reverse }}

first

Returns the first item in a list.

For example:

{{ value|first }}

If value is the list ("a" "b" "c"), the output will be "a".

join

Joins a list with a string.

For example:

{{ value|join:" // " }}

If value is the list ("a" "b" "c"), the output will be the string "a // b // c".

last

Returns the last item in a list.

For example:

{{ value|last }}

If value is the list ("a" "b" "c" "d"), the output will be the string "d".

length

Returns the length of the value. This works for both strings and lists.

For example:

{{ value|length }}

If value is ("a" "b" "c" "d") or "abcd", the output will be 4.

linebreaks

Replaces line breaks in plain text with appropriate HTML; a single newline becomes an HTML line break (<br />) and a new line followed by a blank line becomes a paragraph break (</p>).

For example:

{{ value|linebreaks }}

If value is Joel\nis a slug, the output will be <p>Joel<br />is a slug</p>.

linebreaksbr

Converts all newlines in a piece of plain text to HTML line breaks (<br />).

For example:

{{ value|linebreaksbr }}

If value is Joel\nis a slug, the output will be Joel<br />is a slug.

lower

Converts a string into all lowercase.

For example:

{{ value|lower }}

If value is Still MAD At Yoko, the output will be still mad at yoko.

safe

Marks a string as not requiring further HTML escaping prior to output. When autoescaping is off, this filter has no effect.

Note

If you are chaining filters, a filter applied after safe can make the contents unsafe again. For example, the following code prints the variable as is, unescaped:

{{ var|safe|escape }}

slice

Returns a slice of a sequence (i.e. lists, vectors, strings)

Uses the Common Lisp cl-slice library.

Syntax:

{{ seq | slice: slices }}

Each slice selects a subset of subscripts along the corresponding axis.

  • A nonnegative integer selects the corresponding index, while a negative integer selects an index counting backwards from the last index:

    {{ list | slice: 4 }}
    

if the list is (1 2 3 4 5 6) it will output (5)

  • (start . end) to select a range. When end is NIL, the last index is included.

Each boundary is resolved according to the other rules if applicable, so you can use negative integers:

{{ string | slice: (0 . 5) }}
{{ string | slice: (5 . nil) }}

if the string is "Hello world" is will output Hello and world.

format

Formats the variable according to the argument, a string formatting specifier. This specifier uses Common Lisp string formatting syntax

For example:

{{ value | format:"~:d" }}

If value is 1000000, the output will be 1,000,000.

time

Formats a time according to the given format.

For example:

{{ value | time }}

truncatechars

Truncates a string if it is longer than the specified number of characters. Truncated strings will end with a translatable ellipsis sequence (”...”).

Argument: Number of characters to truncate to

For example:

{{ value|truncatechars:9 }}

If value is "Joel is a slug", the output will be "Joel i...".

upper

Converts a string into all uppercase.

For example:

{{ value|upper }}

If value is "Joel is a slug", the output will be "JOEL IS A SLUG".

urlencode

Escapes a value for use in a URL.

For example:

{{ value|urlencode }}

If value is "http://www.example.org/foo?a=b&c=d", the output will be "http%3A//www.example.org/foo%3Fa%3Db%26c%3Dd".

An optional argument containing the characters which should not be escaped can be provided.

If not provided, the ‘/’ character is assumed safe. An empty string can be provided when all characters should be escaped. For example:

{{ value|urlencode:"" }}

If value is "http://www.example.org/", the output will be "http%3A%2F%2Fwww.example.org%2F".

Custom filters

TODO