Jinja2 template context
Use this page to write a template and check which variables and filters you can use.
Facet renders Jinja2 templates in three places: the display_name label
and the search text of a doctype, both on the server, and the calendar
chip title of a collection view, in the browser.
This page gives the variables each template binds and the filters the server engine registers.
Where templates run
Section titled “Where templates run”| Template | Declared on | Rendered | Engine |
|---|---|---|---|
display_name |
The doctype definition | On the server, on every document write. The result is the document label, truncated to 255 characters. | Full Jinja2 subset (Crinja), filters included |
search |
The doctype definition | On the server, on every document write. The result is the search text: whitespace-normalised, accent-folded, truncated to 256 characters. | Full Jinja2 subset (Crinja), filters included |
config.calendar.title_template |
A core.CollectionView document |
In the browser, for each calendar chip. | Minimal subset: {{ path }} placeholders only |
A write that renders a broken server template fails and rolls back. A missing field never fails — it renders empty.
Context variables — server templates
Section titled “Context variables — server templates”| Name | Type | Content |
|---|---|---|
<field_name> |
The field’s type | One variable per declared field, bound to the field’s value after the write. Dotted paths walk into object fields: {{ address.postal_code }}. |
content |
object | The raw document content tree, for paths the declared fields do not shape: {{ content.address.postal_code }}. |
display_name |
string | The document’s label. Bound in search templates only. A display_name template must not reference it — the save rejects the self-reference. |
Rules the validator enforces at save time:
- Every root variable must be a declared field or a reserved variable.
{{ id }}is rejected — the document id is not a variable. Declare a string field for a human-facing code and print that field. - Variables used only inside
{% if %}or{% for %}arguments are not validated.
How values render
Section titled “How values render”| Value kind | Renders as |
|---|---|
| Reference field | The referenced document’s stored label. An unresolved reference shows the target doctype’s bare name, never the id. A collection reference shows its first entry. |
| Money field | The currency and the amount: USD 120000. Nested money objects format the same way. |
| Absent field | Empty text. A nested path over an absent field renders empty too. |
| Array | Python style: ['a', 'b']. Use join for readable output. |
| Object printed as a leaf | Empty text. |
| HTML or quotes | Verbatim. Autoescape is off; templates produce plain text. |
Two quirks matter in practice:
- An empty string is truthy.
{% if nick %}runs fornick = "". Compare with{{ nick == '' }}when the empty value must fail the check. - A global function shadows a field. A name such as
rangehides a field of the same name.
Registered filters
Section titled “Registered filters”The server engine registers these filters. Arguments are named
arguments, for example {{ tags | join(', ') }} or
{{ price | round(2) }}.
| Filter | Arguments | Effect |
|---|---|---|
abs |
— | Absolute value of a number. |
append |
string |
Appends the string after the value. |
attr |
name |
Reads the attribute name from an object. |
batch |
linecount, fill_with |
Slices an array into rows of linecount items. |
capitalize |
— | Upper-cases the first character, lower-cases the rest. |
center |
width |
Pads the value with spaces to width. |
count |
— | Alias of length. |
d |
— | Alias of default. |
date |
format |
Formats a time value with the given pattern. Field values are strings, so this filter rarely applies to them. |
default |
default_value, boolean |
Falls back to default_value when the value is empty. With boolean=true, also when it is falsy. |
dictsort |
case_sensitive, by |
Sorts a dictionary by key (by="key", the default) or value. |
e |
— | Alias of escape. |
escape |
— | HTML-escapes the value. Autoescape is off, so use it only when HTML output is wanted. |
filesizeformat |
binary |
Formats a byte count as 1.5 kB or, with binary=true, 1.5 KiB. |
first |
— | First item of an array. |
float |
default |
Converts to a float; default when the value is not a number. |
forceescape |
— | HTML-escapes the value, even inside a marked-safe string. |
format |
— | sprintf-style formatting: `{{ “%d items” |
groupby |
attribute |
Groups an array by an attribute. |
indent |
width, indentfirst |
Indents each line by width spaces. |
int |
default, base |
Converts to an integer; default when the value is not a number. |
join |
separator, attribute |
Joins an array into one string. The filter most templates need. |
last |
— | Last item of an array. |
length |
— | Item count of an array or string. |
list |
— | Converts the value to an array. |
lower |
— | Lower-cases the value. |
map |
attribute, or a filter name |
Picks one attribute from each item, or applies a filter to each item. |
pprint |
verbose |
Pretty-prints the value for debugging. |
prepend |
string |
Puts the string before the value. |
random |
— | One random item of an array. |
reject |
— | Keeps the items a test rejects. |
rejectattr |
— | Keeps the items whose attribute a test rejects. |
replace |
old, new, count |
Replaces occurrences of old with new. |
reverse |
— | Reverses an array or string. |
round |
precision, method, base |
Rounds a number to precision digits. |
safe |
— | Marks the value safe from escaping. |
select |
— | Keeps the items a test accepts. |
selectattr |
— | Keeps the items whose attribute a test accepts. |
slice |
slices, fill_with |
Slices an array into slices roughly even parts. |
sort |
reverse, case_sensitive, attribute |
Sorts an array, optionally by an attribute. |
striptags |
— | Removes HTML tags and collapses whitespace. |
sum |
attribute, start |
Sums the items, or their attribute. |
title |
— | Title-cases each word. |
tojson |
indent |
Serialises the value as JSON. |
trim |
— | Strips whitespace from both ends. |
truncate |
length, killwords, end, leeway |
Cuts the string to length and appends end. |
upper |
— | Upper-cases the value. |
urlencode |
— | URL-encodes the value. |
urlize |
trim_url_limit, nofollow, target, rel |
Turns URLs in text into links. |
wordcount |
— | Counts the words. |
wordwrap |
width, break_long_words, wrapstring |
Wraps text at width characters. |
xmlattr |
autoescape |
Serialises a dictionary as HTML attributes. |
A missing or unknown filter raises an error at render time. The write that triggered the render is rejected.
Context variables — calendar title template
Section titled “Context variables — calendar title template”The calendar title_template renders in the browser against a smaller
rule set:
| Name | Content |
|---|---|
<field_name> |
A declared field of the parent doctype. |
content |
The raw document content tree, through the content. prefix. |
created_at, updated_at |
The system timestamps of the document. |
display_name is rejected in this template — the chip falls back to it
when no template is set. The browser renderer supports placeholders
only:
- Filters,
{% if %}blocks, and{# #}comments render verbatim, not as an error. - A missing field renders empty.
- A money object renders as
EUR 100. - An array renders with the items joined by
,.
Save-time validation still checks the syntax and every root variable, so a template that could never render is rejected at authoring time.
Full example
Section titled “Full example”A hr.Person doctype declares the fields first_name, last_name,
email, tags (array of string), salary (money), and manager_id
(reference to hr.Person). The definition carries:
display_name: "{{ last_name | upper }}, {{ first_name }} — {{ salary }}"search: "{{ first_name }} {{ last_name }} {{ email }} {{ tags | join(', ') }}"A document stores:
{ "first_name": "Ada", "last_name": "Lovelace", "email": "ada@facet.local", "tags": ["crm", "vip"], "salary": { "value": "120000", "currency": "USD" }, "manager_id": "hr.Person.01JCATPMKP4N82GVG2J7K4MHZZ"}The stored label is:
LOVELACE, Ada — USD 120000The stored search text is:
Ada Lovelace ada@facet.local crm, vipThe {{ manager_id }} variable would print the referenced person’s
stored label; the two templates above do not use it.
Related
Section titled “Related”- Display names and search text (Jinja2) — write the two doctype templates.
- View templates — the structured view templates, a separate format.
- Computed fields — Lua functions, not templates.