Next: Templates composition, Previous: Verbatim, Up: Top [Contents][Index]
• Overview | ||
• List of filters | ||
• Custom filters | ||
Next: List of filters, Up: Filters [Contents][Index]
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:
Next: Custom filters, Previous: Overview<2>, Up: Filters [Contents][Index]
• add | ||
• addslashes | ||
• capfirst | ||
• cut | ||
• date | ||
• time | ||
• datetime | ||
• default | ||
• reverse | ||
• divisibleby | ||
• sort | ||
• first | ||
• join | ||
• last | ||
• length | ||
• length_is | ||
• linebreaks | ||
• linebreaksbr | ||
• lower | ||
• make_list | ||
• safe escape | ||
• slice | ||
• force-escape | ||
• format | ||
• replace … with | ||
• rest | ||
• scan | ||
• time | ||
• truncatechars | ||
• upper | ||
• urlencode | ||
Next: addslashes, Up: List of filters [Contents][Index]
Adds the argument to the value.
For example:
{{ value|add:2 }}
If value
is 4
, then the output will be 6
.
Next: capfirst, Previous: add, Up: List of filters [Contents][Index]
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"
.
Next: cut, Previous: addslashes, Up: List of filters [Contents][Index]
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"
.
Next: date, Previous: capfirst, Up: List of filters [Contents][Index]
Removes all values of arg from the given string.
For example:
{{ value|cut:" " }}
If value
is "String with spaces"
, the output will be
"Stringwithspaces"
.
Next: time, Previous: cut, Up: List of filters [Contents][Index]
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
Next: datetime, Previous: date, Up: List of filters [Contents][Index]
Formats a time
Example:
{{ time-now | time }}
Next: default, Previous: time, Up: List of filters [Contents][Index]
Formats a date and time
Example:
{{ time-now | datetime }}
Next: reverse, Previous: datetime, Up: List of filters [Contents][Index]
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
.
Next: divisibleby, Previous: default, Up: List of filters [Contents][Index]
Takes a list and returns that list reversed.
For example:
{{ list | reverse }}
Next: sort, Previous: reverse, Up: List of filters [Contents][Index]
Returns True
if the value is divisible by the argument.
For example:
{{ value|divisibleby:"3" }}
If value
is 21
, the output would be True
.
Next: first, Previous: divisibleby, Up: List of filters [Contents][Index]
Takes a list and returns that list sorted.
For example:
{{ list | sort }}
Next: join, Previous: sort, Up: List of filters [Contents][Index]
Returns the first item in a list.
For example:
{{ value|first }}
If value
is the list ("a" "b" "c")
, the output will be "a"
.
Next: last, Previous: first, Up: List of filters [Contents][Index]
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"
.
Next: length, Previous: join, Up: List of filters [Contents][Index]
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"
.
Next: length_is, Previous: last, Up: List of filters [Contents][Index]
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
.
Next: linebreaks, Previous: length, Up: List of filters [Contents][Index]
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
.
Next: linebreaksbr, Previous: length_is, Up: List of filters [Contents][Index]
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>
.
Next: lower, Previous: linebreaks, Up: List of filters [Contents][Index]
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
.
Next: make_list, Previous: linebreaksbr, Up: List of filters [Contents][Index]
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
.
Next: safe escape, Previous: lower, Up: List of filters [Contents][Index]
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']
.
Next: slice, Previous: make_list, Up: List of filters [Contents][Index]
Marks a string as not requiring further HTML escaping prior to output. When autoescaping is off, this filter has no effect.
|
Next: force-escape, Previous: safe escape, Up: List of filters [Contents][Index]
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
.
Next: format, Previous: slice, Up: List of filters [Contents][Index]
Forces escaping HTML characters (<, >, ', \, &
):
{{ value | force-escape }}
It calls djula::escape-for-html
.
Next: replace … with, Previous: force-escape, Up: List of filters [Contents][Index]
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
.
Next: rest, Previous: format, Up: List of filters [Contents][Index]
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
.
Next: scan, Previous: replace … with, Up: List of filters [Contents][Index]
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")
.
Next: time<2>, Previous: rest, Up: List of filters [Contents][Index]
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
).
Next: truncatechars, Previous: scan, Up: List of filters [Contents][Index]
Formats a time according to the given format.
For example:
{{ value | time }}
Next: upper, Previous: time<2>, Up: List of filters [Contents][Index]
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..."
.
Next: urlencode, Previous: truncatechars, Up: List of filters [Contents][Index]
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"
.
Previous: upper, Up: List of filters [Contents][Index]
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"
.
Previous: List of filters, Up: Filters [Contents][Index]
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))))
Previous: List of filters, Up: Filters [Contents][Index]