Formatting filters applied to placeholder values.

Filters let template authors control how a value is rendered without bloating the placeholder text. They are written Jinja/Liquid style after the variable, separated by |:

{{ invoice.date | date: "%d %B %Y" }}
{{ total | round: 2 | currency: "USD" }}
{{ name | upcase }}
{{ middle_name | default: "—" }}

Filter functions

A filter is a 2-arity function (value, args) -> {:ok, term} | {:error, reason} where value is the raw, un-stringified value resolved from the data (so a %Date{} arrives as a %Date{}, not a string) and args is the list of parsed arguments. Returning a term (not necessarily a string) lets filters chain: the output of one filter becomes the input of the next, and the final value is converted to a string for the document.

On {:error, reason} the chain halts and the failure is reported through the usual Ootempl.PlaceholderError batch reporting.

Nil values

A bare placeholder whose value is nil is reported as a missing-value error. Once a filter is applied, the filter decides how to handle nil: default substitutes a fallback, the numeric/date filters raise a filter error, and the string filters (upcase, etc.) treat nil as an empty string. Use default when a value may legitimately be absent.

Registering and overriding filters

Filters are resolved from three layers, each overriding the previous:

1. The built-ins returned by builtins/0.
2. Application config: config :ootempl, filters: %{"money" => &MyApp.money/2}.
3. A per-call :filters option passed to Ootempl.render/4.

Filter names are matched case-insensitively. Registering a filter under the name of a built-in overrides that built-in.

Built-in filters