mirror of
https://github.com/django/django.git
synced 2024-11-30 07:06:18 +01:00
3d1795d87a
git-svn-id: http://code.djangoproject.com/svn/django/trunk@8332 bcc190cf-cafb-0310-a4f2-bffc1f526a37
1965 lines
62 KiB
Plaintext
1965 lines
62 KiB
Plaintext
==================================================
|
|
The Django template language: For template authors
|
|
==================================================
|
|
|
|
.. admonition:: About this document
|
|
|
|
This document explains the language syntax of the Django template system. If
|
|
you're looking for a more technical perspective on how it works and how to
|
|
extend it, see `The Django template language: For Python programmers`_.
|
|
|
|
Django's template language is designed to strike a balance between power and
|
|
ease. It's designed to feel comfortable to those used to working with HTML. If
|
|
you have any exposure to other text-based template languages, such as Smarty_
|
|
or CheetahTemplate_, you should feel right at home with Django's templates.
|
|
|
|
.. admonition:: Philosophy
|
|
|
|
If you have a background in programming, or if you're used to languages
|
|
like PHP which mix programming code directly into HTML, you'll want to
|
|
bear in mind that the Django template system is not simply Python embedded
|
|
into HTML. This is by design: the template system is meant to express
|
|
presentation, not program logic.
|
|
|
|
The Django template system provides tags which function similarly to some
|
|
programming constructs -- an ``{% if %}`` tag for boolean tests, a ``{%
|
|
for %}`` tag for looping, etc. -- but these are not simply executed as the
|
|
corresponding Python code, and the template system will not execute
|
|
arbitrary Python expressions. Only the tags, filters and syntax listed
|
|
below are supported by default (although you can add `your own
|
|
extensions`_ to the template language as needed).
|
|
|
|
.. _`The Django template language: For Python programmers`: ../templates_python/
|
|
.. _Smarty: http://smarty.php.net/
|
|
.. _CheetahTemplate: http://www.cheetahtemplate.org/
|
|
.. _your own extensions: ../templates_python/#extending-the-template-system
|
|
|
|
Templates
|
|
=========
|
|
|
|
A template is simply a text file. It can generate any text-based format (HTML,
|
|
XML, CSV, etc.).
|
|
|
|
A template contains **variables**, which get replaced with values when the
|
|
template is evaluated, and **tags**, which control the logic of the template.
|
|
|
|
Below is a minimal template that illustrates a few basics. Each element will be
|
|
explained later in this document.::
|
|
|
|
{% extends "base_generic.html" %}
|
|
|
|
{% block title %}{{ section.title }}{% endblock %}
|
|
|
|
{% block content %}
|
|
<h1>{{ section.title }}</h1>
|
|
|
|
{% for story in story_list %}
|
|
<h2>
|
|
<a href="{{ story.get_absolute_url }}">
|
|
{{ story.headline|upper }}
|
|
</a>
|
|
</h2>
|
|
<p>{{ story.tease|truncatewords:"100" }}</p>
|
|
{% endfor %}
|
|
{% endblock %}
|
|
|
|
.. admonition:: Philosophy
|
|
|
|
Why use a text-based template instead of an XML-based one (like Zope's
|
|
TAL)? We wanted Django's template language to be usable for more than
|
|
just XML/HTML templates. At World Online, we use it for e-mails,
|
|
JavaScript and CSV. You can use the template language for any text-based
|
|
format.
|
|
|
|
Oh, and one more thing: Making humans edit XML is sadistic!
|
|
|
|
Variables
|
|
=========
|
|
|
|
Variables look like this: ``{{ variable }}``. When the template engine
|
|
encounters a variable, it evaluates that variable and replaces it with the
|
|
result.
|
|
|
|
Use a dot (``.``) to access attributes of a variable.
|
|
|
|
.. admonition:: Behind the scenes
|
|
|
|
Technically, when the template system encounters a dot, it tries the
|
|
following lookups, in this order:
|
|
|
|
* Dictionary lookup
|
|
* Attribute lookup
|
|
* Method call
|
|
* List-index lookup
|
|
|
|
In the above example, ``{{ section.title }}`` will be replaced with the
|
|
``title`` attribute of the ``section`` object.
|
|
|
|
If you use a variable that doesn't exist, the template system will insert
|
|
the value of the ``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''``
|
|
(the empty string) by default.
|
|
|
|
See `Using the built-in reference`_, below, for help on finding what variables
|
|
are available in a given template.
|
|
|
|
Filters
|
|
=======
|
|
|
|
You can modify variables for display by using **filters**.
|
|
|
|
Filters look like this: ``{{ name|lower }}``. This displays the value of the
|
|
``{{ name }}`` variable after being filtered through the ``lower`` filter,
|
|
which converts text to lowercase. Use a pipe (``|``) to apply a filter.
|
|
|
|
Filters can be "chained." The output of one filter is applied to the next.
|
|
``{{ text|escape|linebreaks }}`` is a common idiom for escaping text contents,
|
|
then converting line breaks to ``<p>`` tags.
|
|
|
|
Some filters take arguments. A filter argument looks like this: ``{{
|
|
bio|truncatewords:30 }}``. This will display the first 30 words of the ``bio``
|
|
variable.
|
|
|
|
Filter arguments that contain spaces must be quoted; for example, to join a list
|
|
with commas and spaced you'd use ``{{ list|join:", " }}``.
|
|
|
|
The `Built-in filter reference`_ below describes all the built-in filters.
|
|
|
|
Tags
|
|
====
|
|
|
|
Tags look like this: ``{% tag %}``. Tags are more complex than variables: Some
|
|
create text in the output, some control flow by performing loops or logic, and
|
|
some load external information into the template to be used by later variables.
|
|
|
|
Some tags require beginning and ending tags (i.e.
|
|
``{% tag %} ... tag contents ... {% endtag %}``). The `Built-in tag reference`_
|
|
below describes all the built-in tags. You can create your own tags, if you
|
|
know how to write Python code.
|
|
|
|
Comments
|
|
========
|
|
|
|
To comment-out part of a line in a template, use the comment syntax: ``{# #}``.
|
|
|
|
For example, this template would render as ``'hello'``::
|
|
|
|
{# greeting #}hello
|
|
|
|
A comment can contain any template code, invalid or not. For example::
|
|
|
|
{# {% if foo %}bar{% else %} #}
|
|
|
|
This syntax can only be used for single-line comments (no newlines are
|
|
permitted between the ``{#`` and ``#}`` delimiters). If you need to comment
|
|
out a multiline portion of the template, see the ``comment`` tag, below__.
|
|
|
|
__ comment_
|
|
|
|
Template inheritance
|
|
====================
|
|
|
|
The most powerful -- and thus the most complex -- part of Django's template
|
|
engine is template inheritance. Template inheritance allows you to build a base
|
|
"skeleton" template that contains all the common elements of your site and
|
|
defines **blocks** that child templates can override.
|
|
|
|
It's easiest to understand template inheritance by starting with an example::
|
|
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<link rel="stylesheet" href="style.css" />
|
|
<title>{% block title %}My amazing site{% endblock %}</title>
|
|
</head>
|
|
|
|
<body>
|
|
<div id="sidebar">
|
|
{% block sidebar %}
|
|
<ul>
|
|
<li><a href="/">Home</a></li>
|
|
<li><a href="/blog/">Blog</a></li>
|
|
</ul>
|
|
{% endblock %}
|
|
</div>
|
|
|
|
<div id="content">
|
|
{% block content %}{% endblock %}
|
|
</div>
|
|
</body>
|
|
</html>
|
|
|
|
This template, which we'll call ``base.html``, defines a simple HTML skeleton
|
|
document that you might use for a simple two-column page. It's the job of
|
|
"child" templates to fill the empty blocks with content.
|
|
|
|
In this example, the ``{% block %}`` tag defines three blocks that child
|
|
templates can fill in. All the ``block`` tag does is to tell the template
|
|
engine that a child template may override those portions of the template.
|
|
|
|
A child template might look like this::
|
|
|
|
{% extends "base.html" %}
|
|
|
|
{% block title %}My amazing blog{% endblock %}
|
|
|
|
{% block content %}
|
|
{% for entry in blog_entries %}
|
|
<h2>{{ entry.title }}</h2>
|
|
<p>{{ entry.body }}</p>
|
|
{% endfor %}
|
|
{% endblock %}
|
|
|
|
The ``{% extends %}`` tag is the key here. It tells the template engine that
|
|
this template "extends" another template. When the template system evaluates
|
|
this template, first it locates the parent -- in this case, "base.html".
|
|
|
|
At that point, the template engine will notice the three ``{% block %}`` tags
|
|
in ``base.html`` and replace those blocks with the contents of the child
|
|
template. Depending on the value of ``blog_entries``, the output might look
|
|
like::
|
|
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<link rel="stylesheet" href="style.css" />
|
|
<title>My amazing blog</title>
|
|
</head>
|
|
|
|
<body>
|
|
<div id="sidebar">
|
|
<ul>
|
|
<li><a href="/">Home</a></li>
|
|
<li><a href="/blog/">Blog</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="content">
|
|
<h2>Entry one</h2>
|
|
<p>This is my first entry.</p>
|
|
|
|
<h2>Entry two</h2>
|
|
<p>This is my second entry.</p>
|
|
</div>
|
|
</body>
|
|
</html>
|
|
|
|
Note that since the child template didn't define the ``sidebar`` block, the
|
|
value from the parent template is used instead. Content within a ``{% block %}``
|
|
tag in a parent template is always used as a fallback.
|
|
|
|
You can use as many levels of inheritance as needed. One common way of using
|
|
inheritance is the following three-level approach:
|
|
|
|
* Create a ``base.html`` template that holds the main look-and-feel of your
|
|
site.
|
|
* Create a ``base_SECTIONNAME.html`` template for each "section" of your
|
|
site. For example, ``base_news.html``, ``base_sports.html``. These
|
|
templates all extend ``base.html`` and include section-specific
|
|
styles/design.
|
|
* Create individual templates for each type of page, such as a news
|
|
article or blog entry. These templates extend the appropriate section
|
|
template.
|
|
|
|
This approach maximizes code reuse and makes it easy to add items to shared
|
|
content areas, such as section-wide navigation.
|
|
|
|
Here are some tips for working with inheritance:
|
|
|
|
* If you use ``{% extends %}`` in a template, it must be the first template
|
|
tag in that template. Template inheritance won't work, otherwise.
|
|
|
|
* More ``{% block %}`` tags in your base templates are better. Remember,
|
|
child templates don't have to define all parent blocks, so you can fill
|
|
in reasonable defaults in a number of blocks, then only define the ones
|
|
you need later. It's better to have more hooks than fewer hooks.
|
|
|
|
* If you find yourself duplicating content in a number of templates, it
|
|
probably means you should move that content to a ``{% block %}`` in a
|
|
parent template.
|
|
|
|
* If you need to get the content of the block from the parent template,
|
|
the ``{{ block.super }}`` variable will do the trick. This is useful
|
|
if you want to add to the contents of a parent block instead of
|
|
completely overriding it. Data inserted using ``{{ block.super }}`` will
|
|
not be automatically escaped (see the `next section`_), since it was
|
|
already escaped, if necessary, in the parent template.
|
|
|
|
* For extra readability, you can optionally give a *name* to your
|
|
``{% endblock %}`` tag. For example::
|
|
|
|
{% block content %}
|
|
...
|
|
{% endblock content %}
|
|
|
|
In larger templates, this technique helps you see which ``{% block %}``
|
|
tags are being closed.
|
|
|
|
Finally, note that you can't define multiple ``{% block %}`` tags with the same
|
|
name in the same template. This limitation exists because a block tag works in
|
|
"both" directions. That is, a block tag doesn't just provide a hole to fill --
|
|
it also defines the content that fills the hole in the *parent*. If there were
|
|
two similarly-named ``{% block %}`` tags in a template, that template's parent
|
|
wouldn't know which one of the blocks' content to use.
|
|
|
|
.. _next section: #automatic-html-escaping
|
|
|
|
Automatic HTML escaping
|
|
=======================
|
|
|
|
**New in Django development version**
|
|
|
|
When generating HTML from templates, there's always a risk that a variable will
|
|
include characters that affect the resulting HTML. For example, consider this
|
|
template fragment::
|
|
|
|
Hello, {{ name }}.
|
|
|
|
At first, this seems like a harmless way to display a user's name, but consider
|
|
what would happen if the user entered his name as this::
|
|
|
|
<script>alert('hello')</script>
|
|
|
|
With this name value, the template would be rendered as::
|
|
|
|
Hello, <script>alert('hello')</script>
|
|
|
|
...which means the browser would pop-up a JavaScript alert box!
|
|
|
|
Similarly, what if the name contained a ``'<'`` symbol, like this?
|
|
|
|
<b>username
|
|
|
|
That would result in a rendered template like this::
|
|
|
|
Hello, <b>username
|
|
|
|
...which, in turn, would result in the remainder of the Web page being bolded!
|
|
|
|
Clearly, user-submitted data shouldn't be trusted blindly and inserted directly
|
|
into your Web pages, because a malicious user could use this kind of hole to
|
|
do potentially bad things. This type of security exploit is called a
|
|
`Cross Site Scripting`_ (XSS) attack.
|
|
|
|
To avoid this problem, you have two options:
|
|
|
|
* One, you can make sure to run each untrusted variable through the
|
|
``escape`` filter (documented below), which converts potentially harmful
|
|
HTML characters to unharmful ones. This was the default solution
|
|
in Django for its first few years, but the problem is that it puts the
|
|
onus on *you*, the developer / template author, to ensure you're escaping
|
|
everything. It's easy to forget to escape data.
|
|
|
|
* Two, you can take advantage of Django's automatic HTML escaping. The
|
|
remainder of this section describes how auto-escaping works.
|
|
|
|
By default in the Django development version, every template automatically
|
|
escapes the output of every variable tag. Specifically, these five characters
|
|
are escaped:
|
|
|
|
* ``<`` is converted to ``<``
|
|
* ``>`` is converted to ``>``
|
|
* ``'`` (single quote) is converted to ``'``
|
|
* ``"`` (double quote) is converted to ``"``
|
|
* ``&`` is converted to ``&``
|
|
|
|
Again, we stress that this behavior is on by default. If you're using Django's
|
|
template system, you're protected.
|
|
|
|
.. _Cross Site Scripting: http://en.wikipedia.org/wiki/Cross-site_scripting
|
|
|
|
How to turn it off
|
|
------------------
|
|
|
|
If you don't want data to be auto-escaped, on a per-site, per-template level or
|
|
per-variable level, you can turn it off in several ways.
|
|
|
|
Why would you want to turn it off? Because sometimes, template variables
|
|
contain data that you *intend* to be rendered as raw HTML, in which case you
|
|
don't want their contents to be escaped. For example, you might store a blob of
|
|
HTML in your database and want to embed that directly into your template. Or,
|
|
you might be using Django's template system to produce text that is *not* HTML
|
|
-- like an e-mail message, for instance.
|
|
|
|
For individual variables
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To disable auto-escaping for an individual variable, use the ``safe`` filter::
|
|
|
|
This will be escaped: {{ data }}
|
|
This will not be escaped: {{ data|safe }}
|
|
|
|
Think of *safe* as shorthand for *safe from further escaping* or *can be
|
|
safely interpreted as HTML*. In this example, if ``data`` contains ``'<b>'``,
|
|
the output will be::
|
|
|
|
This will be escaped: <b>
|
|
This will not be escaped: <b>
|
|
|
|
For template blocks
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
To control auto-escaping for a template, wrap the template (or just a
|
|
particular section of the template) in the ``autoescape`` tag, like so::
|
|
|
|
{% autoescape off %}
|
|
Hello {{ name }}
|
|
{% endautoescape %}
|
|
|
|
The ``autoescape`` tag takes either ``on`` or ``off`` as its argument. At
|
|
times, you might want to force auto-escaping when it would otherwise be
|
|
disabled. Here is an example template::
|
|
|
|
Auto-escaping is on by default. Hello {{ name }}
|
|
|
|
{% autoescape off %}
|
|
This will not be auto-escaped: {{ data }}.
|
|
|
|
Nor this: {{ other_data }}
|
|
{% autoescape on %}
|
|
Auto-escaping applies again: {{ name }}
|
|
{% endautoescape %}
|
|
{% endautoescape %}
|
|
|
|
The auto-escaping tag passes its effect onto templates that extend the
|
|
current one as well as templates included via the ``include`` tag, just like
|
|
all block tags. For example::
|
|
|
|
# base.html
|
|
|
|
{% autoescape off %}
|
|
<h1>{% block title %}{% endblock %}</h1>
|
|
{% block content %}
|
|
{% endblock %}
|
|
{% endautoescape %}
|
|
|
|
|
|
# child.html
|
|
|
|
{% extends "base.html" %}
|
|
{% block title %}This & that{% endblock %}
|
|
{% block content %}{{ greeting }}{% endblock %}
|
|
|
|
Because auto-escaping is turned off in the base template, it will also be
|
|
turned off in the child template, resulting in the following rendered
|
|
HTML when the ``greeting`` variable contains the string ``<b>Hello!</b>``::
|
|
|
|
<h1>This & that</h1>
|
|
<b>Hello!</b>
|
|
|
|
Notes
|
|
-----
|
|
|
|
Generally, template authors don't need to worry about auto-escaping very much.
|
|
Developers on the Python side (people writing views and custom filters) need to
|
|
think about the cases in which data shouldn't be escaped, and mark data
|
|
appropriately, so things Just Work in the template.
|
|
|
|
If you're creating a template that might be used in situations where you're
|
|
not sure whether auto-escaping is enabled, then add an ``escape`` filter to any
|
|
variable that needs escaping. When auto-escaping is on, there's no danger of
|
|
the ``escape`` filter *double-escaping* data -- the ``escape`` filter does not
|
|
affect auto-escaped variables.
|
|
|
|
String literals and automatic escaping
|
|
--------------------------------------
|
|
|
|
As we mentioned earlier, filter arguments can be strings::
|
|
|
|
{{ data|default:"This is a string literal." }}
|
|
|
|
All string literals are inserted **without** any automatic escaping into the
|
|
template -- they act as if they were all passed through the ``safe`` filter.
|
|
The reasoning behind this is that the template author is in control of what
|
|
goes into the string literal, so they can make sure the text is correctly
|
|
escaped when the template is written.
|
|
|
|
This means you would write ::
|
|
|
|
{{ data|default:"3 < 2" }}
|
|
|
|
...rather than ::
|
|
|
|
{{ data|default:"3 < 2" }} <-- Bad! Don't do this.
|
|
|
|
This doesn't affect what happens to data coming from the variable itself.
|
|
The variable's contents are still automatically escaped, if necessary, because
|
|
they're beyond the control of the template author.
|
|
|
|
Using the built-in reference
|
|
============================
|
|
|
|
Django's admin interface includes a complete reference of all template tags and
|
|
filters available for a given site. To see it, go to your admin interface and
|
|
click the "Documentation" link in the upper right of the page.
|
|
|
|
The reference is divided into 4 sections: tags, filters, models, and views.
|
|
|
|
The **tags** and **filters** sections describe all the built-in tags (in fact,
|
|
the tag and filter references below come directly from those pages) as well as
|
|
any custom tag or filter libraries available.
|
|
|
|
The **views** page is the most valuable. Each URL in your site has a separate
|
|
entry here, and clicking on a URL will show you:
|
|
|
|
* The name of the view function that generates that view.
|
|
* A short description of what the view does.
|
|
* The **context**, or a list of variables available in the view's template.
|
|
* The name of the template or templates that are used for that view.
|
|
|
|
Each view documentation page also has a bookmarklet that you can use to jump
|
|
from any page to the documentation page for that view.
|
|
|
|
Because Django-powered sites usually use database objects, the **models**
|
|
section of the documentation page describes each type of object in the system
|
|
along with all the fields available on that object.
|
|
|
|
Taken together, the documentation pages should tell you every tag, filter,
|
|
variable and object available to you in a given template.
|
|
|
|
Custom tag and filter libraries
|
|
===============================
|
|
|
|
Certain applications provide custom tag and filter libraries. To access them in
|
|
a template, use the ``{% load %}`` tag::
|
|
|
|
{% load comments %}
|
|
|
|
{% comment_form for blogs.entries entry.id with is_public yes %}
|
|
|
|
In the above, the ``load`` tag loads the ``comments`` tag library, which then
|
|
makes the ``comment_form`` tag available for use. Consult the documentation
|
|
area in your admin to find the list of custom libraries in your installation.
|
|
|
|
The ``{% load %}`` tag can take multiple library names, separated by spaces.
|
|
Example::
|
|
|
|
{% load comments i18n %}
|
|
|
|
Custom libraries and template inheritance
|
|
-----------------------------------------
|
|
|
|
When you load a custom tag or filter library, the tags/filters are only made
|
|
available to the current template -- not any parent or child templates along
|
|
the template-inheritance path.
|
|
|
|
For example, if a template ``foo.html`` has ``{% load comments %}``, a child
|
|
template (e.g., one that has ``{% extends "foo.html" %}``) will *not* have
|
|
access to the comments template tags and filters. The child template is
|
|
responsible for its own ``{% load comments %}``.
|
|
|
|
This is a feature for the sake of maintainability and sanity.
|
|
|
|
Built-in tag and filter reference
|
|
=================================
|
|
|
|
For those without an admin site available, reference for the stock tags and
|
|
filters follows. Because Django is highly customizable, the reference in your
|
|
admin should be considered the final word on what tags and filters are
|
|
available, and what they do.
|
|
|
|
Built-in tag reference
|
|
----------------------
|
|
|
|
autoescape
|
|
~~~~~~~~~~
|
|
|
|
**New in Django development version**
|
|
|
|
Control the current auto-escaping behavior. This tag takes either ``on`` or
|
|
``off`` as an argument and that determines whether auto-escaping is in effect
|
|
inside the block.
|
|
|
|
When auto-escaping is in effect, all variable content has HTML escaping applied
|
|
to it before placing the result into the output (but after any filters have
|
|
been applied). This is equivalent to manually applying the ``escape`` filter
|
|
to each variable.
|
|
|
|
The only exceptions are variables that are already marked as "safe" from
|
|
escaping, either by the code that populated the variable, or because it has had
|
|
the ``safe`` or ``escape`` filters applied.
|
|
|
|
block
|
|
~~~~~
|
|
|
|
Define a block that can be overridden by child templates. See
|
|
`Template inheritance`_ for more information.
|
|
|
|
comment
|
|
~~~~~~~
|
|
|
|
Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
|
|
|
|
cycle
|
|
~~~~~
|
|
|
|
**Changed in Django development version**
|
|
Cycle among the given strings or variables each time this tag is encountered.
|
|
|
|
Within a loop, cycles among the given strings/variables each time through the
|
|
loop::
|
|
|
|
{% for o in some_list %}
|
|
<tr class="{% cycle 'row1' 'row2' rowvar %}">
|
|
...
|
|
</tr>
|
|
{% endfor %}
|
|
|
|
Outside of a loop, give the values a unique name the first time you call it,
|
|
then use that name each successive time through::
|
|
|
|
<tr class="{% cycle 'row1' 'row2' rowvar as rowcolors %}">...</tr>
|
|
<tr class="{% cycle rowcolors %}">...</tr>
|
|
<tr class="{% cycle rowcolors %}">...</tr>
|
|
|
|
You can use any number of values, separated by spaces. Values enclosed in
|
|
single (') or double quotes (") are treated as string literals, while values
|
|
without quotes are assumed to refer to context variables.
|
|
|
|
You can also separate values with commas::
|
|
|
|
{% cycle row1,row2,row3 %}
|
|
|
|
In this syntax, each value will be interpreted as literal text. The
|
|
comma-based syntax exists for backwards-compatibility, and should not be
|
|
used for new projects.
|
|
|
|
debug
|
|
~~~~~
|
|
|
|
Output a whole load of debugging information, including the current context and
|
|
imported modules.
|
|
|
|
extends
|
|
~~~~~~~
|
|
|
|
Signal that this template extends a parent template.
|
|
|
|
This tag can be used in two ways:
|
|
|
|
* ``{% extends "base.html" %}`` (with quotes) uses the literal value
|
|
``"base.html"`` as the name of the parent template to extend.
|
|
|
|
* ``{% extends variable %}`` uses the value of ``variable``. If the variable
|
|
evaluates to a string, Django will use that string as the name of the
|
|
parent template. If the variable evaluates to a ``Template`` object,
|
|
Django will use that object as the parent template.
|
|
|
|
See `Template inheritance`_ for more information.
|
|
|
|
filter
|
|
~~~~~~
|
|
|
|
Filter the contents of the variable through variable filters.
|
|
|
|
Filters can also be piped through each other, and they can have arguments --
|
|
just like in variable syntax.
|
|
|
|
Sample usage::
|
|
|
|
{% filter force_escape|lower %}
|
|
This text will be HTML-escaped, and will appear in all lowercase.
|
|
{% endfilter %}
|
|
|
|
firstof
|
|
~~~~~~~
|
|
|
|
Outputs the first variable passed that is not False. Outputs nothing if all the
|
|
passed variables are False.
|
|
|
|
Sample usage::
|
|
|
|
{% firstof var1 var2 var3 %}
|
|
|
|
This is equivalent to::
|
|
|
|
{% if var1 %}
|
|
{{ var1 }}
|
|
{% else %}{% if var2 %}
|
|
{{ var2 }}
|
|
{% else %}{% if var3 %}
|
|
{{ var3 }}
|
|
{% endif %}{% endif %}{% endif %}
|
|
|
|
You can also use a literal string as a fallback value in case all
|
|
passed variables are False::
|
|
|
|
{% firstof var1 var2 var3 "fallback value" %}
|
|
|
|
for
|
|
~~~
|
|
|
|
Loop over each item in an array. For example, to display a list of athletes
|
|
provided in ``athlete_list``::
|
|
|
|
<ul>
|
|
{% for athlete in athlete_list %}
|
|
<li>{{ athlete.name }}</li>
|
|
{% endfor %}
|
|
</ul>
|
|
|
|
You can loop over a list in reverse by using ``{% for obj in list reversed %}``.
|
|
|
|
**New in Django development version**
|
|
If you need to loop over a list of lists, you can unpack the values
|
|
in each sub-list into individual variables. For example, if your context
|
|
contains a list of (x,y) coordinates called ``points``, you could use the
|
|
following to output the list of points::
|
|
|
|
{% for x, y in points %}
|
|
There is a point at {{ x }},{{ y }}
|
|
{% endfor %}
|
|
|
|
This can also be useful if you need to access the items in a dictionary.
|
|
For example, if your context contained a dictionary ``data``, the following
|
|
would display the keys and values of the dictionary::
|
|
|
|
{% for key, value in data.items %}
|
|
{{ key }}: {{ value }}
|
|
{% endfor %}
|
|
|
|
The for loop sets a number of variables available within the loop:
|
|
|
|
========================== ================================================
|
|
Variable Description
|
|
========================== ================================================
|
|
``forloop.counter`` The current iteration of the loop (1-indexed)
|
|
``forloop.counter0`` The current iteration of the loop (0-indexed)
|
|
``forloop.revcounter`` The number of iterations from the end of the
|
|
loop (1-indexed)
|
|
``forloop.revcounter0`` The number of iterations from the end of the
|
|
loop (0-indexed)
|
|
``forloop.first`` True if this is the first time through the loop
|
|
``forloop.last`` True if this is the last time through the loop
|
|
``forloop.parentloop`` For nested loops, this is the loop "above" the
|
|
current one
|
|
========================== ================================================
|
|
|
|
if
|
|
~~
|
|
|
|
The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.
|
|
exists, is not empty, and is not a false boolean value) the contents of the
|
|
block are output::
|
|
|
|
{% if athlete_list %}
|
|
Number of athletes: {{ athlete_list|length }}
|
|
{% else %}
|
|
No athletes.
|
|
{% endif %}
|
|
|
|
In the above, if ``athlete_list`` is not empty, the number of athletes will be
|
|
displayed by the ``{{ athlete_list|length }}`` variable.
|
|
|
|
As you can see, the ``if`` tag can take an optional ``{% else %}`` clause that
|
|
will be displayed if the test fails.
|
|
|
|
``if`` tags may use ``and``, ``or`` or ``not`` to test a number of variables or
|
|
to negate a given variable::
|
|
|
|
{% if athlete_list and coach_list %}
|
|
Both athletes and coaches are available.
|
|
{% endif %}
|
|
|
|
{% if not athlete_list %}
|
|
There are no athletes.
|
|
{% endif %}
|
|
|
|
{% if athlete_list or coach_list %}
|
|
There are some athletes or some coaches.
|
|
{% endif %}
|
|
|
|
{% if not athlete_list or coach_list %}
|
|
There are no athletes or there are some coaches (OK, so
|
|
writing English translations of boolean logic sounds
|
|
stupid; it's not our fault).
|
|
{% endif %}
|
|
|
|
{% if athlete_list and not coach_list %}
|
|
There are some athletes and absolutely no coaches.
|
|
{% endif %}
|
|
|
|
``if`` tags don't allow ``and`` and ``or`` clauses within the same tag, because
|
|
the order of logic would be ambiguous. For example, this is invalid::
|
|
|
|
{% if athlete_list and coach_list or cheerleader_list %}
|
|
|
|
If you need to combine ``and`` and ``or`` to do advanced logic, just use nested
|
|
``if`` tags. For example::
|
|
|
|
{% if athlete_list %}
|
|
{% if coach_list or cheerleader_list %}
|
|
We have athletes, and either coaches or cheerleaders!
|
|
{% endif %}
|
|
{% endif %}
|
|
|
|
Multiple uses of the same logical operator are fine, as long as you use the
|
|
same operator. For example, this is valid::
|
|
|
|
{% if athlete_list or coach_list or parent_list or teacher_list %}
|
|
|
|
ifchanged
|
|
~~~~~~~~~
|
|
|
|
Check if a value has changed from the last iteration of a loop.
|
|
|
|
The 'ifchanged' block tag is used within a loop. It has two possible uses.
|
|
|
|
1. Checks its own rendered contents against its previous state and only
|
|
displays the content if it has changed. For example, this displays a list of
|
|
days, only displaying the month if it changes::
|
|
|
|
<h1>Archive for {{ year }}</h1>
|
|
|
|
{% for date in days %}
|
|
{% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
|
|
<a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
|
|
{% endfor %}
|
|
|
|
2. If given a variable, check whether that variable has changed. For
|
|
example, the following shows the date every time it changes, but
|
|
only shows the hour if both the hour and the date have changed::
|
|
|
|
{% for date in days %}
|
|
{% ifchanged date.date %} {{ date.date }} {% endifchanged %}
|
|
{% ifchanged date.hour date.date %}
|
|
{{ date.hour }}
|
|
{% endifchanged %}
|
|
{% endfor %}
|
|
|
|
The ``ifchanged`` tag also takes an optional ``{% else %}`` clause that will
|
|
be displayed if the value has not changed::
|
|
|
|
{% for match in matches %}
|
|
<div style="background-color:
|
|
{% ifchanged match.ballot_id %}
|
|
{% cycle red,blue %}
|
|
{% else %}
|
|
grey
|
|
{% endifchanged %}
|
|
">{{ match }}</div>
|
|
{% endfor %}
|
|
|
|
ifequal
|
|
~~~~~~~
|
|
|
|
Output the contents of the block if the two arguments equal each other.
|
|
|
|
Example::
|
|
|
|
{% ifequal user.id comment.user_id %}
|
|
...
|
|
{% endifequal %}
|
|
|
|
As in the ``{% if %}`` tag, an ``{% else %}`` clause is optional.
|
|
|
|
The arguments can be hard-coded strings, so the following is valid::
|
|
|
|
{% ifequal user.username "adrian" %}
|
|
...
|
|
{% endifequal %}
|
|
|
|
It is only possible to compare an argument to template variables or strings.
|
|
You cannot check for equality with Python objects such as ``True`` or
|
|
``False``. If you need to test if something is true or false, use the ``if``
|
|
tag instead.
|
|
|
|
ifnotequal
|
|
~~~~~~~~~~
|
|
|
|
Just like ``ifequal``, except it tests that the two arguments are not equal.
|
|
|
|
include
|
|
~~~~~~~
|
|
|
|
Loads a template and renders it with the current context. This is a way of
|
|
"including" other templates within a template.
|
|
|
|
The template name can either be a variable or a hard-coded (quoted) string,
|
|
in either single or double quotes.
|
|
|
|
This example includes the contents of the template ``"foo/bar.html"``::
|
|
|
|
{% include "foo/bar.html" %}
|
|
|
|
This example includes the contents of the template whose name is contained in
|
|
the variable ``template_name``::
|
|
|
|
{% include template_name %}
|
|
|
|
An included template is rendered with the context of the template that's
|
|
including it. This example produces the output ``"Hello, John"``:
|
|
|
|
* Context: variable ``person`` is set to ``"john"``.
|
|
* Template::
|
|
|
|
{% include "name_snippet.html" %}
|
|
|
|
* The ``name_snippet.html`` template::
|
|
|
|
Hello, {{ person }}
|
|
|
|
See also: ``{% ssi %}``.
|
|
|
|
load
|
|
~~~~
|
|
|
|
Load a custom template tag set.
|
|
|
|
See `Custom tag and filter libraries`_ for more information.
|
|
|
|
now
|
|
~~~
|
|
|
|
Display the date, formatted according to the given string.
|
|
|
|
Uses the same format as PHP's ``date()`` function (http://php.net/date)
|
|
with some custom extensions.
|
|
|
|
Available format strings:
|
|
|
|
================ ======================================== =====================
|
|
Format character Description Example output
|
|
================ ======================================== =====================
|
|
a ``'a.m.'`` or ``'p.m.'`` (Note that ``'a.m.'``
|
|
this is slightly different than PHP's
|
|
output, because this includes periods
|
|
to match Associated Press style.)
|
|
A ``'AM'`` or ``'PM'``. ``'AM'``
|
|
b Month, textual, 3 letters, lowercase. ``'jan'``
|
|
B Not implemented.
|
|
d Day of the month, 2 digits with ``'01'`` to ``'31'``
|
|
leading zeros.
|
|
D Day of the week, textual, 3 letters. ``'Fri'``
|
|
f Time, in 12-hour hours and minutes, ``'1'``, ``'1:30'``
|
|
with minutes left off if they're zero.
|
|
Proprietary extension.
|
|
F Month, textual, long. ``'January'``
|
|
g Hour, 12-hour format without leading ``'1'`` to ``'12'``
|
|
zeros.
|
|
G Hour, 24-hour format without leading ``'0'`` to ``'23'``
|
|
zeros.
|
|
h Hour, 12-hour format. ``'01'`` to ``'12'``
|
|
H Hour, 24-hour format. ``'00'`` to ``'23'``
|
|
i Minutes. ``'00'`` to ``'59'``
|
|
I Not implemented.
|
|
j Day of the month without leading ``'1'`` to ``'31'``
|
|
zeros.
|
|
l Day of the week, textual, long. ``'Friday'``
|
|
L Boolean for whether it's a leap year. ``True`` or ``False``
|
|
m Month, 2 digits with leading zeros. ``'01'`` to ``'12'``
|
|
M Month, textual, 3 letters. ``'Jan'``
|
|
n Month without leading zeros. ``'1'`` to ``'12'``
|
|
N Month abbreviation in Associated Press ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'``
|
|
style. Proprietary extension.
|
|
O Difference to Greenwich time in hours. ``'+0200'``
|
|
P Time, in 12-hour hours, minutes and ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'``
|
|
'a.m.'/'p.m.', with minutes left off
|
|
if they're zero and the special-case
|
|
strings 'midnight' and 'noon' if
|
|
appropriate. Proprietary extension.
|
|
r RFC 2822 formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'``
|
|
s Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'``
|
|
S English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'``
|
|
month, 2 characters.
|
|
t Number of days in the given month. ``28`` to ``31``
|
|
T Time zone of this machine. ``'EST'``, ``'MDT'``
|
|
U Not implemented.
|
|
w Day of the week, digits without ``'0'`` (Sunday) to ``'6'`` (Saturday)
|
|
leading zeros.
|
|
W ISO-8601 week number of year, with ``1``, ``53``
|
|
weeks starting on Monday.
|
|
y Year, 2 digits. ``'99'``
|
|
Y Year, 4 digits. ``'1999'``
|
|
z Day of the year. ``0`` to ``365``
|
|
Z Time zone offset in seconds. The ``-43200`` to ``43200``
|
|
offset for timezones west of UTC is
|
|
always negative, and for those east of
|
|
UTC is always positive.
|
|
================ ======================================== =====================
|
|
|
|
Example::
|
|
|
|
It is {% now "jS F Y H:i" %}
|
|
|
|
Note that you can backslash-escape a format string if you want to use the
|
|
"raw" value. In this example, "f" is backslash-escaped, because otherwise
|
|
"f" is a format string that displays the time. The "o" doesn't need to be
|
|
escaped, because it's not a format character::
|
|
|
|
It is the {% now "jS o\f F" %}
|
|
|
|
This would display as "It is the 4th of September".
|
|
|
|
regroup
|
|
~~~~~~~
|
|
|
|
Regroup a list of alike objects by a common attribute.
|
|
|
|
This complex tag is best illustrated by use of an example: say that ``people``
|
|
is a list of people represented by dictionaries with ``first_name``,
|
|
``last_name``, and ``gender`` keys::
|
|
|
|
people = [
|
|
{'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
|
|
{'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
|
|
{'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
|
|
{'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
|
|
{'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
|
|
]
|
|
|
|
...and you'd like to display a hierarchical list that is ordered by gender,
|
|
like this:
|
|
|
|
* Male:
|
|
* George Bush
|
|
* Bill Clinton
|
|
* Female:
|
|
* Margaret Thatcher
|
|
* Condoleezza Rice
|
|
* Unknown:
|
|
* Pat Smith
|
|
|
|
You can use the ``{% regroup %}`` tag to group the list of people by gender.
|
|
The following snippet of template code would accomplish this::
|
|
|
|
{% regroup people by gender as gender_list %}
|
|
|
|
<ul>
|
|
{% for gender in gender_list %}
|
|
<li>{{ gender.grouper }}
|
|
<ul>
|
|
{% for item in gender.list %}
|
|
<li>{{ item.first_name }} {{ item.last_name }}</li>
|
|
{% endfor %}
|
|
</ul>
|
|
</li>
|
|
{% endfor %}
|
|
</ul>
|
|
|
|
Let's walk through this example. ``{% regroup %}`` takes three arguments: the
|
|
list you want to regroup, the attribute to group by, and the name of the
|
|
resulting list. Here, we're regrouping the ``people`` list by the ``gender``
|
|
attribute and calling the result ``gender_list``.
|
|
|
|
``{% regroup %}`` produces a list (in this case, ``gender_list``) of
|
|
**group objects**. Each group object has two attributes:
|
|
|
|
* ``grouper`` -- the item that was grouped by (e.g., the string "Male" or
|
|
"Female").
|
|
* ``list`` -- a list of all items in this group (e.g., a list of all people
|
|
with gender='Male').
|
|
|
|
Note that ``{% regroup %}`` does not order its input! Our example relies on
|
|
the fact that the ``people`` list was ordered by ``gender`` in the first place.
|
|
If the ``people`` list did *not* order its members by ``gender``, the regrouping
|
|
would naively display more than one group for a single gender. For example,
|
|
say the ``people`` list was set to this (note that the males are not grouped
|
|
together)::
|
|
|
|
people = [
|
|
{'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
|
|
{'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
|
|
{'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
|
|
{'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
|
|
{'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
|
|
]
|
|
|
|
With this input for ``people``, the example ``{% regroup %}`` template code
|
|
above would result in the following output:
|
|
|
|
* Male:
|
|
* Bill Clinton
|
|
* Unknown:
|
|
* Pat Smith
|
|
* Female:
|
|
* Margaret Thatcher
|
|
* Male:
|
|
* George Bush
|
|
* Female:
|
|
* Condoleezza Rice
|
|
|
|
The easiest solution to this gotcha is to make sure in your view code that the
|
|
data is ordered according to how you want to display it.
|
|
|
|
Another solution is to sort the data in the template using the ``dictsort``
|
|
filter, if your data is in a list of dictionaries::
|
|
|
|
{% regroup people|dictsort:"gender" by gender as gender_list %}
|
|
|
|
spaceless
|
|
~~~~~~~~~
|
|
|
|
Removes whitespace between HTML tags. This includes tab
|
|
characters and newlines.
|
|
|
|
Example usage::
|
|
|
|
{% spaceless %}
|
|
<p>
|
|
<a href="foo/">Foo</a>
|
|
</p>
|
|
{% endspaceless %}
|
|
|
|
This example would return this HTML::
|
|
|
|
<p><a href="foo/">Foo</a></p>
|
|
|
|
Only space between *tags* is removed -- not space between tags and text. In
|
|
this example, the space around ``Hello`` won't be stripped::
|
|
|
|
{% spaceless %}
|
|
<strong>
|
|
Hello
|
|
</strong>
|
|
{% endspaceless %}
|
|
|
|
ssi
|
|
~~~
|
|
|
|
Output the contents of a given file into the page.
|
|
|
|
Like a simple "include" tag, ``{% ssi %}`` includes the contents of another
|
|
file -- which must be specified using an absolute path -- in the current
|
|
page::
|
|
|
|
{% ssi /home/html/ljworld.com/includes/right_generic.html %}
|
|
|
|
If the optional "parsed" parameter is given, the contents of the included
|
|
file are evaluated as template code, within the current context::
|
|
|
|
{% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}
|
|
|
|
Note that if you use ``{% ssi %}``, you'll need to define
|
|
`ALLOWED_INCLUDE_ROOTS`_ in your Django settings, as a security measure.
|
|
|
|
See also: ``{% include %}``.
|
|
|
|
.. _ALLOWED_INCLUDE_ROOTS: ../settings/#allowed-include-roots
|
|
|
|
templatetag
|
|
~~~~~~~~~~~
|
|
|
|
Output one of the syntax characters used to compose template tags.
|
|
|
|
Since the template system has no concept of "escaping", to display one of the
|
|
bits used in template tags, you must use the ``{% templatetag %}`` tag.
|
|
|
|
The argument tells which template bit to output:
|
|
|
|
================== =======
|
|
Argument Outputs
|
|
================== =======
|
|
``openblock`` ``{%``
|
|
``closeblock`` ``%}``
|
|
``openvariable`` ``{{``
|
|
``closevariable`` ``}}``
|
|
``openbrace`` ``{``
|
|
``closebrace`` ``}``
|
|
``opencomment`` ``{#``
|
|
``closecomment`` ``#}``
|
|
================== =======
|
|
|
|
url
|
|
~~~
|
|
|
|
**Note that the syntax for this tag may change in the future, as we make it more robust.**
|
|
|
|
Returns an absolute URL (i.e., a URL without the domain name) matching a given
|
|
view function and optional parameters. This is a way to output links without
|
|
violating the DRY principle by having to hard-code URLs in your templates::
|
|
|
|
{% url path.to.some_view arg1,arg2,name1=value1 %}
|
|
|
|
The first argument is a path to a view function in the format
|
|
``package.package.module.function``. Additional arguments are optional and
|
|
should be comma-separated values that will be used as positional and keyword
|
|
arguments in the URL. All arguments required by the URLconf should be present.
|
|
|
|
For example, suppose you have a view, ``app_views.client``, whose URLconf
|
|
takes a client ID (here, ``client()`` is a method inside the views file
|
|
``app_views.py``). The URLconf line might look like this::
|
|
|
|
('^client/(\d+)/$', 'project_name.app_name.app_views.client')
|
|
|
|
If this app's URLconf is included into the project's URLconf under a path
|
|
such as this::
|
|
|
|
('^clients/', include('project_name.app_name.urls'))
|
|
|
|
...then, in a template, you can create a link to this view like this::
|
|
|
|
{% url project_name.app_name.app_views.client client.id %}
|
|
|
|
The template tag will output the string ``/clients/client/123/``.
|
|
|
|
**New in development version:** If you're using `named URL patterns`_,
|
|
you can refer to the name of the pattern in the ``url`` tag instead of
|
|
using the path to the view.
|
|
|
|
.. _named URL patterns: ../url_dispatch/#naming-url-patterns
|
|
|
|
widthratio
|
|
~~~~~~~~~~
|
|
|
|
For creating bar charts and such, this tag calculates the ratio of a given value
|
|
to a maximum value, and then applies that ratio to a constant.
|
|
|
|
For example::
|
|
|
|
<img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" />
|
|
|
|
Above, if ``this_value`` is 175 and ``max_value`` is 200, the the image in the
|
|
above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5
|
|
which is rounded up to 88).
|
|
|
|
with
|
|
~~~~
|
|
|
|
**New in Django development version**
|
|
|
|
Caches a complex variable under a simpler name. This is useful when accessing
|
|
an "expensive" method (e.g., one that hits the database) multiple times.
|
|
|
|
For example::
|
|
|
|
{% with business.employees.count as total %}
|
|
{{ total }} employee{{ total|pluralize }}
|
|
{% endwith %}
|
|
|
|
The populated variable (in the example above, ``total``) is only available
|
|
between the ``{% with %}`` and ``{% endwith %}`` tags.
|
|
|
|
Built-in filter reference
|
|
-------------------------
|
|
|
|
add
|
|
~~~
|
|
|
|
Adds the argument to the value.
|
|
|
|
For example::
|
|
|
|
{{ value|add:"2" }}
|
|
|
|
If ``value`` is ``4``, then the output will be ``6``.
|
|
|
|
addslashes
|
|
~~~~~~~~~~
|
|
|
|
Adds slashes before quotes. Useful for escaping strings in CSV, for example.
|
|
|
|
**New in Django development version**: For escaping data in JavaScript strings,
|
|
use the `escapejs`_ filter instead.
|
|
|
|
capfirst
|
|
~~~~~~~~
|
|
|
|
Capitalizes the first character of the value.
|
|
|
|
center
|
|
~~~~~~
|
|
|
|
Centers the value in a field of a given width.
|
|
|
|
cut
|
|
~~~
|
|
|
|
Removes all values of arg from the given string.
|
|
|
|
For example::
|
|
|
|
{{ value|cut:" "}}
|
|
|
|
If ``value`` is ``"String with spaces"``, the output will be ``"Stringwithspaces"``.
|
|
|
|
date
|
|
~~~~
|
|
|
|
Formats a date according to the given format (same as the `now`_ tag).
|
|
|
|
For example::
|
|
|
|
{{ value|date:"D d M Y" }}
|
|
|
|
If ``value`` is a ``datetime`` object (e.g., the result of
|
|
``datetime.datetime.now()``), the output will be the string
|
|
``'Wed 09 Jan 2008'``.
|
|
|
|
default
|
|
~~~~~~~
|
|
|
|
If value evaluates to ``False``, use given default. Otherwise, use the value.
|
|
|
|
For example::
|
|
|
|
{{ value|default:"nothing" }}
|
|
|
|
If ``value`` is ``""`` (the empty string), the output will be ``nothing``.
|
|
|
|
default_if_none
|
|
~~~~~~~~~~~~~~~
|
|
|
|
If (and only if) value is ``None``, use given default. Otherwise, use the
|
|
value.
|
|
|
|
Note that if an empty string is given, the default value will *not* be used.
|
|
Use the ``default`` filter if you want to fallback for empty strings.
|
|
|
|
For example::
|
|
|
|
{{ value|default_if_none:"nothing" }}
|
|
|
|
If ``value`` is ``None``, the output will be the string ``"nothing"``.
|
|
|
|
dictsort
|
|
~~~~~~~~
|
|
|
|
Takes a list of dictionaries and returns that list sorted by the key given in
|
|
the argument.
|
|
|
|
For example::
|
|
|
|
{{ value|dictsort:"name" }}
|
|
|
|
If ``value`` is::
|
|
|
|
[
|
|
{'name': 'zed', 'age': 19},
|
|
{'name': 'amy', 'age': 22},
|
|
{'name': 'joe', 'age': 31},
|
|
]
|
|
|
|
then the output would be::
|
|
|
|
[
|
|
{'name': 'amy', 'age': 22},
|
|
{'name': 'joe', 'age': 31},
|
|
{'name': 'zed', 'age': 19},
|
|
]
|
|
|
|
dictsortreversed
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Takes a list of dictionaries and returns that list sorted in reverse order by
|
|
the key given in the argument. This works exactly the same as the above filter,
|
|
but the returned value will be in reverse order.
|
|
|
|
divisibleby
|
|
~~~~~~~~~~~
|
|
|
|
Returns ``True`` if the value is divisible by the argument.
|
|
|
|
For example::
|
|
|
|
{{ value|divisibleby:"3" }}
|
|
|
|
If ``value`` is ``21``, the output would be ``True``.
|
|
|
|
escape
|
|
~~~~~~
|
|
|
|
Escapes a string's HTML. Specifically, it makes these replacements:
|
|
|
|
* ``<`` is converted to ``<``
|
|
* ``>`` is converted to ``>``
|
|
* ``'`` (single quote) is converted to ``'``
|
|
* ``"`` (double quote) is converted to ``"``
|
|
* ``&`` is converted to ``&``
|
|
|
|
The escaping is only applied when the string is output, so it does not matter
|
|
where in a chained sequence of filters you put ``escape``: it will always be
|
|
applied as though it were the last filter. If you want escaping to be applied
|
|
immediately, use the ``force_escape`` filter.
|
|
|
|
Applying ``escape`` to a variable that would normally have auto-escaping
|
|
applied to the result will only result in one round of escaping being done. So
|
|
it is safe to use this function even in auto-escaping environments. If you want
|
|
multiple escaping passes to be applied, use the ``force_escape`` filter.
|
|
|
|
**New in Django development version:** Due to auto-escaping, the behavior of
|
|
this filter has changed slightly. The replacements are only made once, after
|
|
all other filters are applied -- including filters before and after it.
|
|
|
|
escapejs
|
|
~~~~~~~~
|
|
|
|
**New in Django development version**
|
|
|
|
Escapes characters for use in JavaScript strings. This does *not* make the
|
|
string safe for use in HTML, but does protect you from syntax errors when using
|
|
templates to generate JavaScript/JSON.
|
|
|
|
filesizeformat
|
|
~~~~~~~~~~~~~~
|
|
|
|
Format the value like a 'human-readable' file size (i.e. ``'13 KB'``,
|
|
``'4.1 MB'``, ``'102 bytes'``, etc).
|
|
|
|
For example::
|
|
|
|
{{ value|filesizeformat }}
|
|
|
|
If ``value`` is 123456789, the output would be ``117.7 MB``.
|
|
|
|
first
|
|
~~~~~
|
|
|
|
Returns the first item in a list.
|
|
|
|
For example::
|
|
|
|
{{ value|first }}
|
|
|
|
If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``.
|
|
|
|
fix_ampersands
|
|
~~~~~~~~~~~~~~
|
|
|
|
Replaces ampersands with ``&`` entities.
|
|
|
|
For example::
|
|
|
|
{{ value|fix_ampersands }}
|
|
|
|
If ``value`` is ``Tom & Jerry``, the output will be ``Tom & Jerry``.
|
|
|
|
**New in Django development version**: This filter generally is no longer
|
|
useful, because ampersands are automatically escaped in templates. See escape_
|
|
for more on how auto-escaping works.
|
|
|
|
floatformat
|
|
~~~~~~~~~~~
|
|
|
|
When used without an argument, rounds a floating-point number to one decimal
|
|
place -- but only if there's a decimal part to be displayed. For example:
|
|
|
|
============ =========================== ========
|
|
``value`` Template Output
|
|
============ =========================== ========
|
|
``34.23234`` ``{{ value|floatformat }}`` ``34.2``
|
|
``34.00000`` ``{{ value|floatformat }}`` ``34``
|
|
``34.26000`` ``{{ value|floatformat }}`` ``34.3``
|
|
============ =========================== ========
|
|
|
|
If used with a numeric integer argument, ``floatformat`` rounds a number to
|
|
that many decimal places. For example:
|
|
|
|
============ ============================= ==========
|
|
``value`` Template Output
|
|
============ ============================= ==========
|
|
``34.23234`` ``{{ value|floatformat:3 }}`` ``34.232``
|
|
``34.00000`` ``{{ value|floatformat:3 }}`` ``34.000``
|
|
``34.26000`` ``{{ value|floatformat:3 }}`` ``34.260``
|
|
============ ============================= ==========
|
|
|
|
If the argument passed to ``floatformat`` is negative, it will round a number
|
|
to that many decimal places -- but only if there's a decimal part to be
|
|
displayed. For example:
|
|
|
|
============ ================================ ==========
|
|
``value`` Template Output
|
|
============ ================================ ==========
|
|
``34.23234`` ``{{ value|floatformat:"-3" }}`` ``34.232``
|
|
``34.00000`` ``{{ value|floatformat:"-3" }}`` ``34``
|
|
``34.26000`` ``{{ value|floatformat:"-3" }}`` ``34.260``
|
|
============ ================================ ==========
|
|
|
|
Using ``floatformat`` with no argument is equivalent to using ``floatformat``
|
|
with an argument of ``-1``.
|
|
|
|
force_escape
|
|
~~~~~~~~~~~~
|
|
|
|
**New in Django development version**
|
|
|
|
Applies HTML escaping to a string (see the ``escape`` filter for details).
|
|
This filter is applied *immediately* and returns a new, escaped string. This
|
|
is useful in the rare cases where you need multiple escaping or want to apply
|
|
other filters to the escaped results. Normally, you want to use the ``escape``
|
|
filter.
|
|
|
|
get_digit
|
|
~~~~~~~~~
|
|
|
|
Given a whole number, returns the requested digit, where 1 is the right-most
|
|
digit, 2 is the second-right-most digit, etc. Returns the original value for
|
|
invalid input (if input or argument is not an integer, or if argument is less
|
|
than 1). Otherwise, output is always an integer.
|
|
|
|
For example::
|
|
|
|
{{ value|get_digit:"2" }}
|
|
|
|
If ``value`` is ``123456789``, the output will be ``8``.
|
|
|
|
iriencode
|
|
~~~~~~~~~
|
|
|
|
Converts an IRI (Internationalized Resource Identifier) to a string that is
|
|
suitable for including in a URL. This is necessary if you're trying to use
|
|
strings containing non-ASCII characters in a URL.
|
|
|
|
It's safe to use this filter on a string that has already gone through the
|
|
``urlencode`` filter.
|
|
|
|
join
|
|
~~~~
|
|
|
|
Joins a list with a string, like Python's ``str.join(list)``
|
|
|
|
For example::
|
|
|
|
{{ value|join:" // " }}
|
|
|
|
If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string
|
|
``"a // b // c"``.
|
|
|
|
last
|
|
~~~~
|
|
|
|
**New in Django development version.**
|
|
|
|
Returns the last item in a list.
|
|
|
|
For example::
|
|
|
|
{{ value|last }}
|
|
|
|
If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output will be the string
|
|
``"d"``.
|
|
|
|
length
|
|
~~~~~~
|
|
|
|
Returns the length of the value. This works for both strings and lists.
|
|
|
|
For example::
|
|
|
|
{{ value|length }}
|
|
|
|
If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``.
|
|
|
|
length_is
|
|
~~~~~~~~~
|
|
|
|
Returns ``True`` if the value's length is the argument, or ``False`` otherwise.
|
|
|
|
For example::
|
|
|
|
{{ value|length_is:"4" }}
|
|
|
|
If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``True``.
|
|
|
|
linebreaks
|
|
~~~~~~~~~~
|
|
|
|
Replaces line breaks in plain text with appropriate HTML; a single
|
|
newline becomes an HTML line break (``<br />``) and a new line
|
|
followed by a blank line becomes a paragraph break (``</p>``).
|
|
|
|
For example::
|
|
|
|
{{ value|linebreaks }}
|
|
|
|
If ``value`` is ``Joel\nis a slug``, the output will be ``<p>Joel<br>is a
|
|
slug</p>``.
|
|
|
|
linebreaksbr
|
|
~~~~~~~~~~~~
|
|
|
|
Converts all newlines in a piece of plain text to HTML line breaks
|
|
(``<br />``).
|
|
|
|
linenumbers
|
|
~~~~~~~~~~~
|
|
|
|
Displays text with line numbers.
|
|
|
|
ljust
|
|
~~~~~
|
|
|
|
Left-aligns the value in a field of a given width.
|
|
|
|
**Argument:** field size
|
|
|
|
lower
|
|
~~~~~
|
|
|
|
Converts a string into all lowercase.
|
|
|
|
For example::
|
|
|
|
{{ value|lower }}
|
|
|
|
If ``value`` is ``Still MAD At Yoko``, the output will be ``still mad at yoko``.
|
|
|
|
make_list
|
|
~~~~~~~~~
|
|
|
|
Returns the value turned into a list. For an integer, it's a list of
|
|
digits. For a string, it's a list of characters.
|
|
|
|
For example::
|
|
|
|
{{ value|make_list }}
|
|
|
|
If ``value`` is the string ``"Joel"``, the output would be the list
|
|
``[u'J', u'o', u'e', u'l']``. If ``value`` is ``123``, the output will be the
|
|
list ``[1, 2, 3]``.
|
|
|
|
phone2numeric
|
|
~~~~~~~~~~~~~
|
|
|
|
Converts a phone number (possibly containing letters) to its numerical
|
|
equivalent. For example, ``'800-COLLECT'`` will be converted to
|
|
``'800-2655328'``.
|
|
|
|
The input doesn't have to be a valid phone number. This will happily convert
|
|
any string.
|
|
|
|
pluralize
|
|
~~~~~~~~~
|
|
|
|
Returns a plural suffix if the value is not 1. By default, this suffix is ``'s'``.
|
|
|
|
Example::
|
|
|
|
You have {{ num_messages }} message{{ num_messages|pluralize }}.
|
|
|
|
For words that require a suffix other than ``'s'``, you can provide an alternate
|
|
suffix as a parameter to the filter.
|
|
|
|
Example::
|
|
|
|
You have {{ num_walruses }} walrus{{ num_walrus|pluralize:"es" }}.
|
|
|
|
For words that don't pluralize by simple suffix, you can specify both a
|
|
singular and plural suffix, separated by a comma.
|
|
|
|
Example::
|
|
|
|
You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.
|
|
|
|
pprint
|
|
~~~~~~
|
|
|
|
A wrapper around `pprint.pprint`__ -- for debugging, really.
|
|
|
|
__ http://www.python.org/doc/2.5/lib/module-pprint.html
|
|
|
|
random
|
|
~~~~~~
|
|
|
|
Returns a random item from the given list.
|
|
|
|
For example::
|
|
|
|
{{ value|random }}
|
|
|
|
If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``.
|
|
|
|
removetags
|
|
~~~~~~~~~~
|
|
|
|
Removes a space-separated list of [X]HTML tags from the output.
|
|
|
|
For example::
|
|
|
|
{{ value|removetags:"b span"|safe }}
|
|
|
|
If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the
|
|
output will be ``"Joel <button>is</button> a slug"``.
|
|
|
|
rjust
|
|
~~~~~
|
|
|
|
Right-aligns the value in a field of a given width.
|
|
|
|
**Argument:** field size
|
|
|
|
safe
|
|
~~~~
|
|
|
|
Marks a string as not requiring further HTML escaping prior to output. When
|
|
autoescaping is off, this filter has no effect.
|
|
|
|
slice
|
|
~~~~~
|
|
|
|
Returns a slice of the list.
|
|
|
|
Uses the same syntax as Python's list slicing. See
|
|
http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
|
|
for an introduction.
|
|
|
|
Example: ``{{ some_list|slice:":2" }}``
|
|
|
|
slugify
|
|
~~~~~~~
|
|
|
|
Converts to lowercase, removes non-word characters (alphanumerics and
|
|
underscores) and converts spaces to hyphens. Also strips leading and trailing
|
|
whitespace.
|
|
|
|
For example::
|
|
|
|
{{ value|slugify }}
|
|
|
|
If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``.
|
|
|
|
stringformat
|
|
~~~~~~~~~~~~
|
|
|
|
Formats the variable according to the argument, a string formatting specifier.
|
|
This specifier uses Python string formating syntax, with the exception that
|
|
the leading "%" is dropped.
|
|
|
|
See http://docs.python.org/lib/typesseq-strings.html for documentation of
|
|
Python string formatting
|
|
|
|
For example::
|
|
|
|
{{ value|stringformat:"s" }}
|
|
|
|
If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is a slug"``.
|
|
|
|
striptags
|
|
~~~~~~~~~
|
|
|
|
Strips all [X]HTML tags.
|
|
|
|
For example::
|
|
|
|
{{ value|striptags }}
|
|
|
|
If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``, the
|
|
output will be ``"Joel is a slug"``.
|
|
|
|
time
|
|
~~~~
|
|
|
|
Formats a time according to the given format (same as the `now`_ tag).
|
|
The time filter will only accept parameters in the format string that relate
|
|
to the time of day, not the date (for obvious reasons). If you need to
|
|
format a date, use the `date`_ filter.
|
|
|
|
For example::
|
|
|
|
{{ value|time:"H:i" }}
|
|
|
|
If ``value`` is equivalent to ``datetime.datetime.now()``, the output will be
|
|
the string ``"01:23"``.
|
|
|
|
timesince
|
|
~~~~~~~~~
|
|
|
|
Formats a date as the time since that date (e.g., "4 days, 6 hours").
|
|
|
|
Takes an optional argument that is a variable containing the date to use as
|
|
the comparison point (without the argument, the comparison point is *now*).
|
|
For example, if ``blog_date`` is a date instance representing midnight on 1
|
|
June 2006, and ``comment_date`` is a date instance for 08:00 on 1 June 2006,
|
|
then ``{{ comment_date|timesince:blog_date }}`` would return "8 hours".
|
|
|
|
Minutes is the smallest unit used, and "0 minutes" will be returned for any
|
|
date that is in the future relative to the comparison point.
|
|
|
|
timeuntil
|
|
~~~~~~~~~
|
|
|
|
Similar to ``timesince``, except that it measures the time from now until the
|
|
given date or datetime. For example, if today is 1 June 2006 and
|
|
``conference_date`` is a date instance holding 29 June 2006, then
|
|
``{{ conference_date|timeuntil }}`` will return "4 weeks".
|
|
|
|
Takes an optional argument that is a variable containing the date to use as
|
|
the comparison point (instead of *now*). If ``from_date`` contains 22 June
|
|
2006, then ``{{ conference_date|timeuntil:from_date }}`` will return "1 week".
|
|
|
|
Minutes is the smallest unit used, and "0 minutes" will be returned for any
|
|
date that is in the past relative to the comparison point.
|
|
|
|
title
|
|
~~~~~
|
|
|
|
Converts a string into titlecase.
|
|
|
|
truncatewords
|
|
~~~~~~~~~~~~~
|
|
|
|
Truncates a string after a certain number of words.
|
|
|
|
**Argument:** Number of words to truncate after
|
|
|
|
For example::
|
|
|
|
{{ value|truncatewords:2 }}
|
|
|
|
If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is ..."``.
|
|
|
|
truncatewords_html
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
Similar to ``truncatewords``, except that it is aware of HTML tags. Any tags
|
|
that are opened in the string and not closed before the truncation point, are
|
|
closed immediately after the truncation.
|
|
|
|
This is less efficient than ``truncatewords``, so should only be used when it
|
|
is being passed HTML text.
|
|
|
|
unordered_list
|
|
~~~~~~~~~~~~~~
|
|
|
|
Recursively takes a self-nested list and returns an HTML unordered list --
|
|
WITHOUT opening and closing <ul> tags.
|
|
|
|
**New in Django development version:** The format accepted by
|
|
``unordered_list`` has changed to be easier to understand.
|
|
|
|
The list is assumed to be in the proper format. For example, if ``var`` contains
|
|
``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then
|
|
``{{ var|unordered_list }}`` would return::
|
|
|
|
<li>States
|
|
<ul>
|
|
<li>Kansas
|
|
<ul>
|
|
<li>Lawrence</li>
|
|
<li>Topeka</li>
|
|
</ul>
|
|
</li>
|
|
<li>Illinois</li>
|
|
</ul>
|
|
</li>
|
|
|
|
Note: the previous more restrictive and verbose format is still supported:
|
|
``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``,
|
|
|
|
upper
|
|
~~~~~
|
|
|
|
Converts a string into all uppercase.
|
|
|
|
For example::
|
|
|
|
{{ value|upper }}
|
|
|
|
If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``.
|
|
|
|
urlencode
|
|
~~~~~~~~~
|
|
|
|
Escapes a value for use in a URL.
|
|
|
|
urlize
|
|
~~~~~~
|
|
|
|
Converts URLs in plain text into clickable links.
|
|
|
|
Note that if ``urlize`` is applied to text that already contains HTML markup,
|
|
things won't work as expected. Apply this filter only to *plain* text.
|
|
|
|
For example::
|
|
|
|
{{ value|urlize }}
|
|
|
|
If ``value`` is ``"Check out www.djangoproject.com"``, the output will be
|
|
``"Check out <a
|
|
href="http://www.djangoproject.com">www.djangoproject.com</a>"``.
|
|
|
|
urlizetrunc
|
|
~~~~~~~~~~~
|
|
|
|
Converts URLs into clickable links, truncating URLs longer than the given
|
|
character limit.
|
|
|
|
As with urlize_, this filter should only be applied to *plain* text.
|
|
|
|
**Argument:** Length to truncate URLs to
|
|
|
|
For example::
|
|
|
|
{{ value|urlizetrunc:15 }}
|
|
|
|
If ``value`` is ``"Check out www.djangoproject.com"``, the output would be
|
|
``'Check out <a
|
|
href="http://www.djangoproject.com">www.djangopr...</a>'``.
|
|
|
|
wordcount
|
|
~~~~~~~~~
|
|
|
|
Returns the number of words.
|
|
|
|
wordwrap
|
|
~~~~~~~~
|
|
|
|
Wraps words at specified line length.
|
|
|
|
**Argument:** number of characters at which to wrap the text
|
|
|
|
For example::
|
|
|
|
{{ value|wordwrap:5 }}
|
|
|
|
If ``value`` is ``Joel is a slug``, the output would be::
|
|
|
|
Joel
|
|
is a
|
|
slug
|
|
|
|
yesno
|
|
~~~~~
|
|
|
|
Given a string mapping values for true, false and (optionally) None,
|
|
returns one of those strings according to the value:
|
|
|
|
========== ====================== ==================================
|
|
Value Argument Outputs
|
|
========== ====================== ==================================
|
|
``True`` ``"yeah,no,maybe"`` ``yeah``
|
|
``False`` ``"yeah,no,maybe"`` ``no``
|
|
``None`` ``"yeah,no,maybe"`` ``maybe``
|
|
``None`` ``"yeah,no"`` ``"no"`` (converts None to False
|
|
if no mapping for None is given)
|
|
========== ====================== ==================================
|
|
|
|
Other tags and filter libraries
|
|
===============================
|
|
|
|
Django comes with a couple of other template-tag libraries that you have to
|
|
enable explicitly in your ``INSTALLED_APPS`` setting and enable in your
|
|
template with the ``{% load %}`` tag.
|
|
|
|
django.contrib.humanize
|
|
-----------------------
|
|
|
|
A set of Django template filters useful for adding a "human touch" to data. See
|
|
the `humanize documentation`_.
|
|
|
|
.. _humanize documentation: ../add_ons/#humanize
|
|
|
|
django.contrib.markup
|
|
---------------------
|
|
|
|
A collection of template filters that implement these common markup languages:
|
|
|
|
* Textile
|
|
* Markdown
|
|
* ReST (ReStructured Text)
|
|
|
|
See the `markup section`_ of the `add-ons documentation`_ for more
|
|
information.
|
|
|
|
.. _markup section: ../add_ons/#markup
|
|
.. _add-ons documentation: ../add_ons/
|
|
|
|
django.contrib.webdesign
|
|
------------------------
|
|
|
|
A collection of template tags that can be useful while designing a Web site,
|
|
such as a generator of Lorem Ipsum text. See the `webdesign documentation`_.
|
|
|
|
.. _webdesign documentation: ../webdesign/
|