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]