Template Filters and Helpers

umbral templates run on minijinja 2, which ships a Jinja2-compatible filter set out of the box. On top of that standard library, umbral-core registers a handful of custom filters and functions of its own (img, markdown, sanitize, currency, static, media_url, now, querystring_with, highlight_styles) and injects ambient globals into every render (csrf_token, csrf_input, plus the anonymous-safe user). Plugins can add their own; see Custom template tags.

This page catalogues the filters and globals umbral users reach for most, with examples written in the umbral template style.

umbral's own filters and globals

These are registered by umbral-core's template engine (crates/umbral-core/src/templates.rs) and are available in every .html template the framework renders, on top of the minijinja standard library below.

img, markdown, and sanitize all return safe (pre-escaped) values, so autoescape won't double-encode the markup they generate. The kwargs on img are strict: a typo'd key like alt_text raises a clear template error rather than being silently dropped.

{# user-supplied markdown, rendered and sanitized in one pipe #}
<div class="prose">{{ plugin.usage \| markdown }}</div>
 
{# CLS-safe responsive image #}
{{ logo_url \| img(alt=plugin.name, width=64, height=64, class="logo") }}

Plugins register their own app-level filters and functions through Plugin::template_registrars; see Custom template tags. (The admin plugin additionally registers a naturaltime filter against its private environment; that one is scoped to admin templates and isn't available in app-level templates.)

String filters

{# templates/profile.html #}
<h1>{{ user.name | title }}</h1>
<p>{{ bio | default("No bio.") }}</p>

Number filters

<p>Price: {{ product.price | round(2) }}</p>
<p>In stock: {{ inventory | abs }}</p>

List and collection filters

{# Comma-separated tag names #}
<p>Tags: {{ article.tags | map(attribute="name") | join(", ") }}</p>
 
{# First three items only #}
{% for item in items | list | slice(3) | first %}
  <li>{{ item.title }}</li>
{% endfor %}
 
{# Total pages: 12 #}
<p>Total pages: {{ pages | length }}</p>

Default and type-testing filters

<p>{{ user.bio | default("No bio provided.") }}</p>
<script>
  const data = {{ payload | tojson }};
</script>

Control-flow tags (not filters, but commonly confused)

These are Jinja2 tags, not pipe filters. They're included here because they solve the same display problems that humanize-style filters solve.

{# Conditional blocks #}
{% if articles | length == 0 %}
  <p>No articles yet.</p>
{% else %}
  <p>{{ articles | length }} article{% if articles | length != 1 %}s{% endif %}</p>
{% endif %}
 
{# Loop helpers inside a for block #}
{% for item in items %}
  {# loop.index is 1-based; loop.index0 is 0-based #}
  <li class="{% if loop.first %}first{% endif %} {% if loop.last %}last{% endif %}">
    {{ loop.index }}. {{ item.name }}
  </li>
{% endfor %}

Global functions

minijinja exposes a small set of global functions callable anywhere in a template expression.

{% for i in range(1, 6) %}
  <p>Item {{ i }}</p>
{% endfor %}

The safe filter and autoescape

umbral enables autoescape on every .html and .htm template. A value that contains <script> will be emitted as <script> automatically. To render pre-trusted HTML - for example, a sanitised rich-text field - pipe it through safe:

{# Only do this for content you have already sanitised server-side #}
<div class="body">{{ article.rendered_html | safe }}</div>

There is no global escape bypass. See Rendering HTML for the security rationale.

What is missing today: humanize helpers

Humanize-style filters - the friendly date/number formatters like naturalday, naturaltime, intcomma, ordinal, and filesizeformat - are a known category of template helper. minijinja 2 does not ship these, and umbral-core does not register app-level equivalents yet (the admin plugin ships a naturaltime filter, but it's scoped to admin templates only). When humanize-style filters land for app templates they will be documented here.

In the meantime, compute humanized representations in the handler and pass them as context values:

// handler: pre-compute the human-readable string
let context = context! {
    article,
    created_label => humantime::format_duration(elapsed).to_string(),
};
let html = umbral::templates::render("article.html", &context)?;

{# template: consume it like any other variable #}
<time>{{ created_label }}</time>

See also

• minijinja filter reference - full API docs for every built-in filter, including type signatures and edge cases.
• minijinja test reference - built-in tests usable in {% if value is defined %} / {% if value is divisibleby(3) %} style.
• Rendering HTML - the engine wiring, autoescape policy, and handler integration.
• arch.md §4.5 - the template security rationale and the deferred custom-filter design.