Module filters

Help

Expand description

Filter functions and abstractions.

MiniJinja inherits from Jinja2 the concept of filter functions. These are functions which are applied to values to modify them. For example the expression {{ 42|filter(23) }} invokes the filter filter with the arguments 42 and 23.

MiniJinja comes with some built-in filters that are listed below. To create a custom filter write a function that takes at least a value, then registers it with add_filter.

§Using Filters

Using filters in templates is possible in all places an expression is permitted. This means they are not just used for printing but also are useful for iteration or similar situations.

Motivating example:

<dl>
{% for key, value in config|items %}
  <dt>{{ key }}
  <dd><pre>{{ value|tojson }}</pre>
{% endfor %}
</dl>

§Custom Filters

A custom filter is just a simple function which accepts its inputs as parameters and then returns a new value. For instance the following shows a filter which takes an input value and replaces whitespace with dashes and converts it to lowercase:

fn slugify(value: String) -> String {
    value.to_lowercase().split_whitespace().collect::<Vec<_>>().join("-")
}

env.add_filter("slugify", slugify);

MiniJinja will perform the necessary conversions automatically. For more information see the Function trait.

§Accessing State

In some cases it can be necessary to access the execution State. Since a borrowed state implements ArgType it’s possible to add a parameter that holds the state. For instance the following filter appends the current template name to the string:

use minijinja::{Value, State};

fn append_template(state: &State, value: &Value) -> String {
    format!("{}-{}", value, state.name())
}

env.add_filter("append_template", append_template);

§Filter configuration

The recommended pattern for filters to change their behavior is to leverage global variables in the template. For instance take a filter that performs date formatting. You might want to change the default time format format on a per-template basis without having to update every filter invocation. In this case the recommended pattern is to reserve upper case variables and look them up in the filter:

use minijinja::State;

fn timeformat(state: &State, ts: f64) -> String {
    let configured_format = state.lookup("TIME_FORMAT");
    let format = configured_format
        .as_ref()
        .and_then(|x| x.as_str())
        .unwrap_or("HH:MM:SS");
    format_unix_timestamp(ts, format)
}

env.add_filter("timeformat", timeformat);

This then later lets a user override the default either by using add_global or by passing it with the context! macro or similar.

let ctx = context! {
    TIME_FORMAT => "HH:MM",
    ..other_variables
};

§Built-in Filters

When the builtins feature is enabled a range of built-in filters are automatically added to the environment. These are also all provided in this module. Note though that these functions are not to be called from Rust code as their exact interface (arguments and return types) might change from one MiniJinja version to another.

Some additional filters are available in the minijinja-contrib crate.

Traits§

Filter: A utility trait that represents global functions.

Functions§

abs: Returns the absolute value of a number.
attr: Looks up an attribute.
batch: Batch items.
bool: Converts the value into a boolean value.
capitalize: Convert the string with all its characters lowercased apart from the first char which is uppercased.
default: If the value is undefined it will return the passed default value, otherwise the value of the variable:
dictsort: Dict sorting functionality.
escape: Escapes a string. By default to HTML.
first: Returns the first item from an iterable.
float: Converts a value into a float.
groupby: Group a sequence of objects by an attribute.
indent: Indents Value with spaces
int: Converts a value into an integer.
items: Returns an iterable of pairs (items) from a mapping.
join: Joins a sequence by a character
last: Returns the last item from an iterable.
length: Returns the “length” of the value
lines: Splits a string into lines.
list: Converts the input value into a list.
lower: Converts a value to lowercase.
map: Applies a filter to a sequence of objects or looks up an attribute.
max: Returns the largest item from an iterable.
min: Returns the smallest item from an iterable.
pprint: Pretty print a variable.
reject: Creates a new sequence of values that don’t pass a test.
rejectattr: Creates a new sequence of values of which an attribute does not pass a test.
replace: Does a string replace.
reverse: Reverses an iterable or string
round: Round the number to a given precision.
safe: Marks a value as safe. This converts it into a string.
select: Creates a new sequence of values that pass a test.
selectattr: Creates a new sequence of values of which an attribute passes a test.
slice: Slice an iterable and return a list of lists containing those items.
sort: Returns the sorted version of the given list.
split: Split a string into its substrings, using split as the separator string.
string: Converts a value into a string if it’s not one already.
sum: Sums up all the values in a sequence.
title: Converts a value to title case.
tojson: Dumps a value to JSON.
trim: Trims a value
unique: Returns a list of unique items from the given iterable.
upper: Converts a value to uppercase.
urlencode: URL encodes a value.

Module filtersCopy item path