Skip to content
This repository has been archived by the owner on Jun 4, 2022. It is now read-only.

Templating Reference

Adrian Cochrane edited this page May 28, 2018 · 22 revisions

For syntax, refer to Django's documentation.

{% autoescape mode %}

Sets the autoescaping mode. mode may be one of 'off', 'html', 'html-lines', 'js-string', 'csv', 'uri'/'url' or to restore the previous mode 'end'.

{% debug %}

Outputs all variables accessible at this point in the template as a <dl> list. Intended for debugging purposes, not production.

{% fetch %}

Evaluates the contained template until {% each %} to obtain a whitespace seperated list of HTTP or HTTPS URLs to download concurrently. Template rendering resumes after {% endfetch %} once all URLs have been downloaded.

{% fetch permacache %}

Cache the request permanantly following standard caching headers. This is a normal HTTP cache, except nothing ever gets evicted due to lack of storage space.

This is potentially useful for autoupdating "addons" registered in the database as URIs.

{% each as name %}

For each HTTP response obtained from fetch, each renders it's contained template until {% endfetch %} with the parsed response stored in name.

The response is parsed as TSV or JSON (XML support is planned) according to the MIMEtype given by the server. If that MIMEtype is absent, it will be inferred.

{% filter filters %}

Applies filters to the contained template until {% endfilter %}. filters uses templating syntax, without the variable path or the preceding |.

{% for [key] value in variable %}

Evaluates the contained template until {% endfor %} (or {% empty %}) for each item contained in variable. Each time it assigns the item to value (which must be a global name), and the corrosponding key to key.

{% empty %}

Evaluates the contained template until {% endfor %} if there are no items in variable.

{% if condition... %}

Evaluates the condition, and if truthy evaluates the contained template until {% endif %} (or {% else %} or {% elif %}). The condition is a variable, or variables with infix operators (documented next) between them. Spaces are required between variables and operators.

Operators

In order of precedance (lowest binding to highest binding):

  • or
  • and
  • not (prefix)
  • <, >, <=, >=, ==/=, !=
  • % (This is mostly useful for localization to select between plural forms)

Any operator may be prefixed with not to negate it.

{% else %}

If the expression evaluated to something falsy, evaluates the contained template until {% endif %}.

{% elif alt-condition... %}

If the expression evaluated to something falsy and the contained template until the next {% elif %} or {% endif %}.

{% ifchanged variables... %}

Checks if any of the variables have changed since the last time this code was run. If so it runs the embedded template until {% endif %} (or {% else %}).

{% else %}

Evaluates if there are no changes.

{% macro name ... %}

Defines a new tag identified by name which takes [*key*=]*value*... arguments and applies those variables to the {% macro %}'s contained template until {% endmacro %}. The arguments to {% macro %} are actually meaningless, but they can be used to document expected arguments for the newly defined tags.

Only macros defined after this one are not available in the macro's body. And the macro will be evaluated as if the code was fully spelled out where the macro is called, but that only really makes a difference for {% ifchanged %}.

{% query [limit] %}

Evaluates the SQL queries given by the contained template until {% each-row %}, {% empty %}, {% except %}, or {% endquery %}, and fetches limit rows of them combined. If limit is not specified, all rows will be fetched. Any embedded variable values will be passed to the query as strings and do not require quoting.

For performance and correctness, the valid tags within this subtemplate are a lot more limited. Specifically you can only use variables, {% trans %}, {% with %}, and anything defined via {% macro %}.

SQL syntax errors are reported the same way as Prosody syntax errors, and any runtime errors renders as a red level-1 heading with an error icon.

{% each-row %}

Runs the contained template until {% empty %} or {% endquery %} for each fetched row, exposing all columns of that row as variables.

{% empty %}

Evaluates the contained template until {% endquery %} in the event that none of the queries yield any results.

{% except %}

Evaluates the SQL queries given by the contained template until {% each-row %}, {% empty %}, or {% endquery %} for each row fetched by the outer {% query %}. If any of these queries give no results, ignore that fetched row and do not count it.

The columns of the fetched row are exposed to the subtemplate as variables, and the same rules that apply to {% query %}'s subtemplate also applies here.

{% random %}

Parses all subtemplates seperated by {% alt %} until {% endrandom %}, and upon evaluation chooses a random one of those to render in it's place.

{% templatetag type %}

As per Django.

{% trans [[name=]variable]... %}

Translates the contained template until {% endtrans %} (or {% plural %}), possibly using the additional variables specified in the tag. It is courtious to avoid markup and templating where possible within the the body of a trans tag.

A preceding comment within this subtemplate may be split out specially by localization UIs.

{% with [key=]var... %}

Evaluates the contained template using the given additional variables.

Filters

Where not documented, these should be self-describing. If they're not, please document them here.

|add:y

|alloc:range

Assuming the value being filtered is a number that's kept as small as possible, maps it uniquely to another number evenly dispersed betwen 0 & range. Commonly used in combination with CSS hsl() colors.

|capfirst

|cut:toremove

|date:fmt?

|default:fallbackvalue

|escape

|favicon

Finds the favicon associated with this URI string.

|filesize

|first

|force-escape:mode

mode is as-per {% autoescape mode %}.

|join:deliminator

|last

|length

|lengthis:expected

|lower

|safe

|title