Built-in filters

[andylibrian]

Tracking down the built-in filters available in jinja2. So that people can pick these to contribute. Feel free to add / remove items.

ref: https://jinja.palletsprojects.com/en/2.11.x/templates/#builtin-filters

• abs
• attr (doesn't really make sense in Rust, unlike in python)
• batch
• capitalize
• center
• default
• dictsort
• escape
• filesizeformat (https://github.com/djc/askama/pull/161)
• first
• float
• forceescape
• format
• groupby
• indent (https://github.com/djc/askama/pull/131)
• int
• join
• last
• length (aliases: count)
• list
• lower
• map
• pprint
• random
• reject
• rejectattr
• replace
• reverse
• round
• safe
• select
• selectattr
• slice
• sort
• string
• striptags
• sum
• title
• tojson
• trim
• truncate
• upper
• urlencode
• urlize
• wordcount
• wordwrap
• xmlattr

[djc]

Thank you, this is really useful!

Note that I'm anything but committed to necessarily copying over all the built-in filters; some of these probably don't make much sense with Rust; others might need an amount of complexity that I'm not sure would make sense to always carry in Askama. But the simple ones probably should all join, and trim is a good example of that.

@mitsuhiko, any thoughts about how you selected whether things could go in the built-ins in Jinja? Any that you regret adding?

[mitsuhiko]

As of 2017 I'm quite happy with the filters and tests that exist. The ones I feel are unnecessary are upper and lower because realistically you can also convert to string and upper/lower then.

striptags I always thought should not be there because it's quite dirty but it turns out to be reasonably useful in cases where HTML is already passed to a template but you actually want to render a text email.

dictsort and groupby could be better but it's hard to improve now.

[mitsuhiko]

BTW. I do still plan on porting MarkupSafe to rust. In case there is demand in this (that comes up with filters in Jinja a ton) I can spend some effort on that sooner.

[defyrlt]

@djc: what do you think join filter should work with? A few random options:

• T: AsRef<[String]>
• A: AsRef<str>, T: AsRef<[A]> (I would go with this one)
• T: AsRef<[Display]>
• 'a, T: AsRef<[&'a Display + 'a]>

Upd: added https://github.com/djc/askama/pull/39, let's continue API discussion there

[defyrlt]

@djc: could you please clean up the list to leave things you think make sense as filters in askama, so it's easier for contributors to start working on them?

[djc]

@defyrlt good to see your enthusiasm for contributing!

Personally, I mostly prefer that people mention filters that they actually have a use for in their Rust code, rather than us just blindly implementing all the filters for Jinja compatibility.

That said, some other high-level guidance:

• I think a lot of the type conversions are not necessarily as useful in Rust, where we have a strong type system and the input context is expected to be well-typed already.
• I prefer filters that can be implemented simply with no extra dependencies required, that is, making functionality from Rust's stdlib easily available to templates.

[zzau13]

The following filters are not viable in Rust: attr, default, dictsort, groupby, map, pprint, rejectattr, selectattr, sum and xmlattr.
Some can be done directly in Rust on the template and others don't work in Rust.
You could mark them in the list

[djc]

Could you explain for each of those why you think they aren't viable, please?

[zzau13]

It's because they are filters for Python dictionaries and it has no sense in Rust.

[djc]

Why not? Wouldn't the same thing be relevant for HashMap or BTreeMap?

[zzau13]

Since templates live within the response function, allocating it inside the heap is a serious performance issue.
You can test the Tera filters that use HashMap with frightening results in performance.
It would be better to build help macros for structures with Option<&'a Value> fields.
Like this , the "self" can be set with which the user should do map! (Field, infield, callback).

[djc]

It typically won't be the template allocating: the template is just using an allocated HashMap and iterating over it, generating output from the data contained in it. To me that's an important use case for Askama.

[brunobell]

Hi, I can see that abs function is already in askama::filters in source code, but how can I use it in templates?
For now I'm getting this error message: "cannot find function abs in module askama::filters".

And is there any doc about how to write custom filters (especially for numbers)? Thanks!

[brunobell]

And I noticed that the abs filter was removed in docs of v0.9.0 (which was in since v0.7.2). So, what is going on here? thanks @djc

[djc]

I made some changes in 0.9 to make the extra dependencies pulled in by some of the filter implementations optional. In the case of abs, that's the num-traits feature. I tried to make it so that this is enabled by default, but may have failed. Can you investigate?

Defining your own filters is explained in https://docs.rs/askama/0.9.0/askama/#filters, is that explanation not clear enough?