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 >>:tfilter:‘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:
Adds the argument to the value.
For example:
{{ value|add:2 }}
If value
is 4
, then the output will be 6
.
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"
.
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"
.
Removes all values of arg from the given string.
For example:
{{ value|cut:" " }}
If value
is "String with spaces"
, the output will be
"Stringwithspaces"
.
Formats a date
{{ date-today | date }}
A LOCAL-TIME format spec can be provided:
(defvar timestamp 3752179200) {{ timestamp | date:(:year "/" (:month 2) "/" (:day 2)) }} ;; shows 2018/11/26
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
.
Returns True
if the value is divisible by the argument.
For example:
{{ value|divisibleby:"3" }}
If value
is 21
, the output would be True
.
Returns the first item in a list.
For example:
{{ value|first }}
If value
is the list ("a" "b" "c")
, the output will be "a"
.
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"
.
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"
.
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
.
Returns True
if the value’s length is the argument, or False
otherwise.
For example:
{{ value|length_is:"4" }}
If value
is ['a', 'b', 'c', 'd']
or "abcd"
, the output will be
True
.
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>
.
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
.
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
.
Returns the value turned into a list. For a string, it’s a list of characters. For an integer, the argument is cast into an unicode string before creating a list.
For example:
{{ value|make_list }}
If value
is the string "Joel"
, the output would be the list
['J', 'o', 'e', 'l']
. If value
is 123
, the output will be the
list ['1', '2', '3']
.
Marks a string as not requiring further HTML escaping prior to output. When autoescaping is off, this filter has no effect.
|
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.
{{ 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
.
Forces escaping HTML characters (<, >, ', \, &
):
{{ value | force-escape }}
It calls djula::escape-for-html
.
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
.
The replace
and the with
filters work together:
{{ value | replace:regexp | with:string }}
This will replace all occurences of the regexp in “value” with a new
string, using ppcre:regex-replace-all
.
Returns the rest
of a list (aka cdr
).
For example:
{{ values|rest }}
If values
is the list ("a" "b" "c")
, the output will be ("b" "c")
.
Extracts and displays a regexp from the value:
{{ value | scan:regexp }}
This will display only the text that matches the regexp (using ppcre:scan-to-strings
).
Truncates a string if it is longer than the specified number of characters. Truncated strings will end with the :cl:symbol:ELLISION-STRING, which defaults to “…”.
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..."
.
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"
.
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"
.
Use the def-filter
macro. Its general form is:
(def-filter :myfilter-name (value arg) (body))
It always takes the variable’s value as argument, and it can have one required or optional argument. For example, this is how those built-in filters are defined:
(def-filter :capfirst (val) (string-capitalize (princ-to-string val)))
This is all there is to it. Once written, you can use it in your templates. You can define a filter wherever you want and there is no need to register it or to import it in your templates.
Here’s a filter with a required argument:
(def-filter :add (it n) (+ it (parse-integer n)))
and with an optional one:
(def-filter :datetime (it &optional format) (let ((timestamp …))))
When you need to pass a second argument, make your filter return a
lambda function and chain it with the with
filter:
(def-filter :replace (it regex) (lambda (replace) (ppcre:regex-replace-all regex it replace))) (def-filter :with (it replace) (funcall it replace))
Now we can write:
{{ value | replace:foo | with:bar }}
Errors are handled by the macro, but you can handle them and return a
template-error
condition:
(def-filter :handle-error-filter (it) (handler-case (do-something) (condition (e) (template-error "There was an error executing this filter: ~A" e))))