This document lists and shows examples for each of the the built-in Template Filters that are already registered with Modulo template system.
Template Filters
add
Adds the argument to the value. Example:
allow
Given an "allowed list" of comma separated strings, only permit values that
exist exactly the "allowed list". If the value does not exist within the
allowed list, it will produce an empty string (""
). The fact that empty
strings are "falsy" means you can chain together this filter with the default
filter in order to provide a fallback as well, which is demonstrated in the
third example. Examples:
Note: You should not use this for input validation for security purposes (use
the backend instead, since any frontend code can be altered by users) or input
validation, for which you use should pattern=
instead since it's built in to
HTML.
camelcase
Converts a kebab-case-style-string
(like favored by HTML, or website URL
slugs), among other formats, into a camelCase
(like what's favored by
JavaScript, others).
capfirst
Output given string with the first letter capitalized.
combine
Combine is for combining values, which results in a few different operations depending on type. For Arrays, it will combine them end-to-end. For Objects, it will attempt to "squash" them. See the following examples:
default
If the given value is Falsy, use the given default. Otherwise, use the value.
divisibleby
Returns true
if the value is evenly divisible by the given argument.
entries
Convert the entire Object an Array format. If you only want one part of it, see the related values and keys.
escapejs
Escape special characters in a given string using JavaScript (specifically,
JSON) escaping rules. If you have a string like "Hello\nWorld!"
(where \n
is a single new-line character), it will output Hello\nWorld!
(that is, as
"backslash-n" or two characters). It will also "double-up" any backslashes it
encounters.
Note that this is unrelated to the HTML autoescaping, meaning you may need to also mark as |safe
if do not want it escaping for HTML rules as well (e.g. changing <
, which is invalid for HTML text but valid for JavaScript, into <
). Similarly, there is no need to use this for escaping for HTML attribute values (e.g. <input placeholder="{{ state.msg }}">
), as the HTML escaping is sufficient. The only use is embedded JS strings.
first
Retrieve the first item in an Array:
join
Formats an array to be comma-separated. Optionally, a different separator can be specified as an argument.
json
Formats given data as a JSON string. It takes one optional argument, that if specified, will cause indentation by the given amount.
keys
Show only the keys of the given Object, converted into an Array format. See also the similar values and entries.
last
Retrieve the last item in an Array:
length
Determine the length of the given value. This supports Strings, Arrays, and Objects. For Objects, it will return the number of properties on the object.
lower
Display the given string in all lowercase letters.
multiply
Performs the mathematical operation of "multiplication" of the given numbers.
pluralize
Allows for convenient pluralization in many human languages. This is for words in languages where a plural form is used when there is "0" or "2+" items, and a singular form for exactly 1 item. This is useful for the majority of noun and verb conjugations in English, along with many other Indo-European languages.
To use, give it a number (typically, the length of a list), and a comma separated version of two forms of a word. If that number is exactly "1" it will output the second form (or nothing at all, if the second form is not specified), otherwise it will output the first form.
Below are some examples. Note that in the second example, it does not specify a singular form, but instead only specifies an "s" to append to the word "flower" to make it's plural "flowers".
safe
By default, template variables automatically escape the output of every
variable value. Specifically, >
, <
, '
, "
, and &
are all turned into
their "escaped" HTML equivalents, to prevent them from being interpreated as
HTML tags.
|safe
disables this feature. It "marks" the HTML as "safe" for inclusion, and
thus allowed to be interpreted as HTML, and not just display the sourcecode to
the user. Further reading on this topic is in the
Templating section on "Escaping".
See below for example:
skipfirst
Does the opposite of "first" -- takes all except for the first element. It's useful for skipping over data you don't need to process.
You can skip more than one by specifying the optional argument. For example,
with the syntax: |skipfirst:10
, e.g. "skip the first 10".
subtract
Subtracts the argument from the value. Example:
truncate
Cut off the given string after a number of characters specified by the argument. If it has to cut off the string, it will append an "ellipsis" character.
type
Attempts to figure out the JavaScript type of the given value, and returns the type, in all lowercase. Useful for acting differently when data, for example, is a Number, instead of a String.
renderas
A highly useful filter that allows use of re-usable template snippets.
Typically in the format of {{ state.data|renderas:trow }}
, where state.data
is some Object, and there exists a template like with the -name
"trow" that renders that object. The typical usage of this is refactoring templates to conveniently render complex data. This allows you to take complicated bits of template code and refactor it into another smaller, helper, "child" template that is then used within the main template.
The "input" to renderas should always be an Object. The keys and values of that object will populate the "template variables" for that template, meaning you can access them directly as template variables within the child template. As an example, if we renderas
with an Object like {altTitle: "Newest entry"}
, then within the child template the "altTitle" becomes a "top-level" variable, and we can use syntax like {{ altTitle }}
(no need for "." syntax).
Note that the child template will be isolated or "sandboxed" to only have access to properties of the specified object. State, props, script, etc will not be accessible as template variables. This sandboxing is usually good and helps reduce bugs and makes child templates much easier to read. However, sometimes you just want to quickly spit up and refactor a template, meaning you want the child template to behave just like the parent, and you want global variables available, just as they were available to the parent. To include another template without any sandboxing, consider using the include
template-tag.
reversed
Reverses the given input. Typically, this is used to reverse Arrays, such as when you want to iterate over an Array in the opposite direction using a {% for %}
template-tag. If the input is a String or another data type, it will attempt to first convert to an Array.
upper
Display the given string in all uppercase letters.
values
Show only the values of the given Object, converted into an Array format. See also the similar keys and entries.
yesno
The |yesno
filter converts the data into a string. The |yesno
filter is a
handy shortcut with many practical uses when generating HTML and displaying
values from the database.
By default, it will convert true
and other true values into "yes", false
and other false values, and the "placeholder" null
type into a "" (blank),
since that is often used to designate something that is not yet defined (such
as a null value in a database).
When arguments are provided, these substitute these 3 options, as designated by commas.
If a single argument is provided, then both "no" and "null" options get
combined into "", and only "truthy" values will cause the given argument to
show. This is useful for optionally adding a class, and can end up being
simpler than a full if statement. For example, you can quickly add an "active"
class like: <div class="{{ state.visible|yesno:'active' }}">
With two arguments, the default behavior is replaced with the two alternaties. With 3 arguments, then a value is presented for the undefined third value as well.