805 lines
24 KiB
Plaintext
805 lines
24 KiB
Plaintext
|
============================
|
||
|
|
The Django template language
|
||
|
|
============================
|
||
|
|
|
||
|
|
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 like Smarty_ or
|
||
|
|
CheetahTemplate_, you should feel right at home with Django's templates.
|
||
|
|
|
||
|
|
.. _Smarty: http://smarty.php.net/
|
||
|
|
.. _CheetahTemplate: http://www.cheetahtemplate.org/
|
||
|
|
|
||
|
|
What's a template?
|
||
|
|
==================
|
||
|
|
|
||
|
|
A template is simply a text file. All Django templates by convention have
|
||
|
|
".html" extensions, but they can actually generate any text-based format (HTML,
|
||
|
|
XML, CSV, etc.).
|
||
|
|
|
||
|
|
To actually be useful, a template will contain **variables**, which get replaced
|
||
|
|
with values from the database when the template is evaluated, and **tags**,
|
||
|
|
which control the logic of the template.
|
||
|
|
|
||
|
|
Below is a minimal template that I'll be using to illustrate the parts of a template throughout this introduction::
|
||
|
|
|
||
|
|
{% extends base_generic %}
|
||
|
|
|
||
|
|
{% 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 %}
|
||
|
|
|
||
|
|
What's a variable?
|
||
|
|
==================
|
||
|
|
|
||
|
|
Variables look like this: ``{{ variable }}``. When the template engine
|
||
|
|
encounters a variable, it evaluates that variable and replaces the variable with
|
||
|
|
the result. Many variables will be structures with named attributes; you can
|
||
|
|
"drill down" into these structures with dots (``.``), so in the above example ``
|
||
|
|
{{ section.title }}`` will be replaces with the ``title`` attribute of the
|
||
|
|
``section`` object.
|
||
|
|
|
||
|
|
If you use a variable that doesn't exist, it will be silently ignored; the
|
||
|
|
variable will be replaced by nothingness.
|
||
|
|
|
||
|
|
See `Using the built-in reference`_, below, for help on finding what variables
|
||
|
|
are available in a given template.
|
||
|
|
|
||
|
|
Variables may be modified before being displayed by **filters**.
|
||
|
|
|
||
|
|
What's a filter?
|
||
|
|
================
|
||
|
|
|
||
|
|
Filters look like this: ``{{ name|lower }}``. This display the value of the
|
||
|
|
``{{ name }}`` variable after being filtered through the ``lower`` filter which,
|
||
|
|
as you might have guessed, lowercases the text passed through it.
|
||
|
|
|
||
|
|
We use the pipe character to apply filters to emphasize the analogy with filters
|
||
|
|
on a water pipe: text enters one side, has some operation performed on it, and
|
||
|
|
"flows" out the other side. Stretching the analogy to the breaking point,
|
||
|
|
filters may be "chained"; the output of one filter applied to the next: ``{{
|
||
|
|
text|escape|linebreaks }}`` is a common idiom for escaping text contents and
|
||
|
|
then converting line breaks to ``<p>`` tags.
|
||
|
|
|
||
|
|
Certain 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 always are in double quotes.
|
||
|
|
|
||
|
|
The `Built-in filter reference`_ below describes all the built-in filters.
|
||
|
|
|
||
|
|
What's a tag?
|
||
|
|
=============
|
||
|
|
|
||
|
|
Tags look like this: ``{% tag %}``. Tags are much more complex than variables:
|
||
|
|
some create text in the output; some control flow by performing loops, or logic;
|
||
|
|
some load external information into the template to be used by later variables.
|
||
|
|
|
||
|
|
Some tags are "block" tags with matching beginning and ending tags (i.e. ``{% tag %} ... tag contents ... {% endtag %}``. The `Built-in tag reference`_ below describes all the built-in tags.
|
||
|
|
|
||
|
|
Template Inheritance
|
||
|
|
====================
|
||
|
|
|
||
|
|
The most powerful -- and thus the most complex -- part of Django's template
|
||
|
|
engine is template inheritance. In a nutshell, 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::
|
||
|
|
|
||
|
|
<html>
|
||
|
|
<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>
|
||
|
|
|
||
|
|
This template, which we'll call ``base.html`` defines a simple HTML skeleton
|
||
|
|
document that you might use for a simple two-column page. Since this template
|
||
|
|
won't actually be used directly, I've used the ``{% block %}`` tag to define the
|
||
|
|
three blocks that child templates will fill in. All that the ``block`` tag does
|
||
|
|
is to signal to the template engine that a child template may override those
|
||
|
|
portions of the template.
|
||
|
|
|
||
|
|
To use this template, I might define a child template as follows::
|
||
|
|
|
||
|
|
{% extends "base" %}
|
||
|
|
|
||
|
|
{% 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 this template is evaluated, the
|
||
|
|
first step the template engine will perform is to locate the parent template --
|
||
|
|
in this case, "base" (note the dropping of the ".html" extension). At that
|
||
|
|
point, the template engine will notice the three blocks 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::
|
||
|
|
|
||
|
|
<html>
|
||
|
|
<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>
|
||
|
|
|
||
|
|
Note that since the child template did not define the ``sidebar`` block, the
|
||
|
|
value from the parent template is used instead.
|
||
|
|
|
||
|
|
Template inheritance does not have to be only single-level; multi-level
|
||
|
|
inheritance is possible, and indeed, quite useful.
|
||
|
|
|
||
|
|
Here are some tips for working with inheritance:
|
||
|
|
|
||
|
|
* More ``{% block %}`` tags in your base templates are better. Remember,
|
||
|
|
child templates do not 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 on.
|
||
|
|
|
||
|
|
* If you find yourself reproducing the same content in a number of
|
||
|
|
documents, it probably means you should move that content to a
|
||
|
|
new ``{% block %}`` in a parent template.
|
||
|
|
|
||
|
|
* We often prefer to use three-level inheritance: a single base template
|
||
|
|
for the entire site, a set of mid-level templates for each section of
|
||
|
|
the site, and then the individual templates for each page. This
|
||
|
|
maximizes code reuse, and makes adding items to places like the
|
||
|
|
section-wide navigation possible.
|
||
|
|
|
||
|
|
* 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.
|
||
|
|
|
||
|
|
Using the built-in reference
|
||
|
|
============================
|
||
|
|
|
||
|
|
Since Django can be used to develop any sort of site, the tags, filters, and
|
||
|
|
variables available will be different depending on the application. To make it
|
||
|
|
simple to figure out what's available in a given site.
|
||
|
|
|
||
|
|
This documentation is integrated into the administration interface for your
|
||
|
|
sites and 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 perhaps 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 each variable available in the view.
|
||
|
|
* The name of the template or templates that are used for that view.
|
||
|
|
|
||
|
|
The documentation page also has a bookmarklet that you can use to jump from any
|
||
|
|
page to the documentation page for that view.
|
||
|
|
|
||
|
|
Since most of Django revolves around 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.
|
||
|
|
|
||
|
|
Take 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
|
||
|
|
===============================
|
||
|
|
|
||
|
|
As mentioned above, certain applications will provide custom tag and filter
|
||
|
|
libraries. To use them, 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.
|
||
|
|
|
||
|
|
Built-in tag and filter reference
|
||
|
|
=================================
|
||
|
|
|
||
|
|
For those without an admin site available, the reference for the stock tags and
|
||
|
|
filters follows. Since Django is highly customizable, the documentation
|
||
|
|
references in your admin should be considered the final word on these
|
||
|
|
tags/filters.
|
||
|
|
|
||
|
|
Built-in tag reference
|
||
|
|
----------------------
|
||
|
|
|
||
|
|
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
|
||
|
|
`````
|
||
|
|
|
||
|
|
Cycle among the given strings each time this tag is encountered.
|
||
|
|
|
||
|
|
Within a loop, cycles among the given strings each time through
|
||
|
|
the loop::
|
||
|
|
|
||
|
|
{% for o in some_list %}
|
||
|
|
<tr class="{% cycle row1,row2 %}">
|
||
|
|
...
|
||
|
|
</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,row3 as rowcolors %}">...</tr>
|
||
|
|
<tr class="{% cycle rowcolors %}">...</tr>
|
||
|
|
<tr class="{% cycle rowcolors %}">...</tr>
|
||
|
|
|
||
|
|
You can use any number of values, separated by commas. Make sure not to put
|
||
|
|
spaces between the values -- only commas.
|
||
|
|
|
||
|
|
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 may be used in two ways: ``{% extends "base" %}`` (with quotes) uses
|
||
|
|
the literal value "base" as the name of the parent template to extend, or ``{%
|
||
|
|
extends variable %}`` uses the value of ``variable`` as the name of the parent
|
||
|
|
template to extend.
|
||
|
|
|
||
|
|
See `Template inheritance`_ for more information.
|
||
|
|
|
||
|
|
filter
|
||
|
|
``````
|
||
|
|
|
||
|
|
Filter the contents of the blog through variable filters.
|
||
|
|
|
||
|
|
Filters can also be piped through each other, and they can have arguments --
|
||
|
|
just like in variable syntax.
|
||
|
|
|
||
|
|
Sample usage::
|
||
|
|
|
||
|
|
{% filter 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 %}
|
||
|
|
|
||
|
|
but obviously much cleaner!
|
||
|
|
|
||
|
|
for
|
||
|
|
```
|
||
|
|
|
||
|
|
Loop over each item in an array. For example, to display a list of athletes
|
||
|
|
given ``athlete_list``::
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
{% for athlete in athlete_list %}
|
||
|
|
<li>{{ athlete.name }}</li>
|
||
|
|
{% endfor %}
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
You can also loop over a list in reverse by using ``{% for obj in list reversed %}``.
|
||
|
|
|
||
|
|
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.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|count }}
|
||
|
|
{% else %}
|
||
|
|
No athletes.
|
||
|
|
{% endif %}
|
||
|
|
|
||
|
|
In the above, if ``athlete_list`` is not empty, the number of athletes will be
|
||
|
|
displayed by the ``{{ athlete_list|count }}`` variable.
|
||
|
|
|
||
|
|
As you can see, the ``if`` tag can take an option ``{% else %}`` clause that
|
||
|
|
will be displayed if the test fails.
|
||
|
|
|
||
|
|
``if`` tags may use ``or`` or ``not`` to test a number of variables or to negate
|
||
|
|
a given variable::
|
||
|
|
|
||
|
|
{% 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 my fault).
|
||
|
|
{% endif %}
|
||
|
|
|
||
|
|
For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if``
|
||
|
|
tags instead::
|
||
|
|
|
||
|
|
{% if athlete_list %}
|
||
|
|
{% if coach_list %}
|
||
|
|
Number of athletes: {{ athlete_list|count }}.
|
||
|
|
Number of coaches: {{ coach_list|count }}.
|
||
|
|
{% endif %}
|
||
|
|
{% endif %}
|
||
|
|
|
||
|
|
ifchanged
|
||
|
|
`````````
|
||
|
|
|
||
|
|
Check if a value has changed from the last iteration of a loop.
|
||
|
|
|
||
|
|
The 'ifchanged' block tag is used within a loop. It checks its own rendered
|
||
|
|
contents against its previous state and only displays its content if the value
|
||
|
|
has changed::
|
||
|
|
|
||
|
|
<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 %}
|
||
|
|
|
||
|
|
ifnotequal
|
||
|
|
``````````
|
||
|
|
|
||
|
|
Output the contents of the block if the two arguments do not equal each other.
|
||
|
|
|
||
|
|
Example::
|
||
|
|
|
||
|
|
{% ifnotequal user.id_ comment.user_id %}
|
||
|
|
...
|
||
|
|
{% endifnotequal %}
|
||
|
|
|
||
|
|
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; see http://php.net/date
|
||
|
|
for all the possible values.
|
||
|
|
|
||
|
|
Sample usage::
|
||
|
|
|
||
|
|
It is {% now "jS F Y H:i" %}
|
||
|
|
|
||
|
|
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 ``Person`` objects that have ``first_name``, ``last_name``, and
|
||
|
|
``gender`` attributes, and you'd like to display a list that looks like:
|
||
|
|
|
||
|
|
* Male:
|
||
|
|
* George Bush
|
||
|
|
* Bill Clinton
|
||
|
|
* Female:
|
||
|
|
* Margaret Thatcher
|
||
|
|
* Colendeeza Rice
|
||
|
|
* Unknown:
|
||
|
|
* Janet Reno
|
||
|
|
|
||
|
|
The following snippet of template code would accomplish this dubious task::
|
||
|
|
|
||
|
|
{% regroup people by gender as grouped %}
|
||
|
|
<ul>
|
||
|
|
{% for group in grouped %}
|
||
|
|
<li>{{ group.grouper }}
|
||
|
|
<ul>
|
||
|
|
{% for item in group.list %}
|
||
|
|
<li>{{ item }}</li>
|
||
|
|
{% endfor %}
|
||
|
|
</ul>
|
||
|
|
{% endfor %}
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
As you can see, ``{% regroup %}`` populates a variable with a list of objects
|
||
|
|
with ``grouper`` and ``list`` attributes. ``grouper`` contains the item that
|
||
|
|
was grouped by; ``list`` contains the list of objects that share that
|
||
|
|
``grouper``. In this case, ``grouper`` would be ``Male``, ``Female`` and
|
||
|
|
``Unknown``, and ``list`` is the list of people with those genders.
|
||
|
|
|
||
|
|
Note that ``{% regroup %}`` does not work when the list to be grouped is not
|
||
|
|
sorted by the key you are grouping by! This means that if your list of people
|
||
|
|
was not sorted by gender, you'd need to make sure it is sorted before using it,
|
||
|
|
i.e.::
|
||
|
|
|
||
|
|
{% regroup people|dictsort:"gender" by gender as grouped %}
|
||
|
|
|
||
|
|
ssi
|
||
|
|
```
|
||
|
|
|
||
|
|
Output the contents of a given file into the page.
|
||
|
|
|
||
|
|
Like a simple "include" tag, the ``ssi`` tag includes the contents
|
||
|
|
of another file -- which must be specified using an absolute page --
|
||
|
|
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, with the current context::
|
||
|
|
|
||
|
|
{% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}
|
||
|
|
|
||
|
|
templatetag
|
||
|
|
```````````
|
||
|
|
|
||
|
|
Output one of the bits 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`` ``}}``
|
||
|
|
================== =======
|
||
|
|
|
||
|
|
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).
|
||
|
|
|
||
|
|
Built-in filter reference
|
||
|
|
-------------------------
|
||
|
|
|
||
|
|
add
|
||
|
|
```
|
||
|
|
Adds the arg to the value
|
||
|
|
|
||
|
|
addslashes
|
||
|
|
``````````
|
||
|
|
Adds slashes - useful for passing strings to JavaScript, for example.
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
date
|
||
|
|
````
|
||
|
|
Formats a date according to the given format (same as the now_ tag)
|
||
|
|
|
||
|
|
default
|
||
|
|
```````
|
||
|
|
If value is unavailable, use given default
|
||
|
|
|
||
|
|
dictsort
|
||
|
|
````````
|
||
|
|
Takes a list of dicts, returns that list sorted by the property given in the
|
||
|
|
argument.
|
||
|
|
|
||
|
|
dictsortreversed
|
||
|
|
````````````````
|
||
|
|
Takes a list of dicts, returns that list sorted in reverse order by the property
|
||
|
|
given in the argument.
|
||
|
|
|
||
|
|
divisibleby
|
||
|
|
```````````
|
||
|
|
Returns true if the value is divisible by the argument
|
||
|
|
|
||
|
|
escape
|
||
|
|
``````
|
||
|
|
Escapes a string's HTML
|
||
|
|
|
||
|
|
filesizeformat
|
||
|
|
``````````````
|
||
|
|
Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102
|
||
|
|
bytes, etc).
|
||
|
|
|
||
|
|
first
|
||
|
|
`````
|
||
|
|
Returns the first item in a list
|
||
|
|
|
||
|
|
fix_ampersands
|
||
|
|
``````````````
|
||
|
|
Replaces ampersands with ``&`` entities
|
||
|
|
|
||
|
|
floatformat
|
||
|
|
```````````
|
||
|
|
Displays a floating point number as 34.2 (with one decimal places) - but
|
||
|
|
only if there's a point to be displayed
|
||
|
|
|
||
|
|
get_digit
|
||
|
|
`````````
|
||
|
|
Given a whole number, returns the requested digit of it, 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.
|
||
|
|
|
||
|
|
join
|
||
|
|
````
|
||
|
|
Joins a list with a string, like Python's ``str.join(list)``
|
||
|
|
|
||
|
|
length
|
||
|
|
``````
|
||
|
|
Returns the length of the value - useful for lists
|
||
|
|
|
||
|
|
length_is
|
||
|
|
`````````
|
||
|
|
Returns a boolean of whether the value's length is the argument
|
||
|
|
|
||
|
|
linebreaks
|
||
|
|
``````````
|
||
|
|
Converts newlines into <p> and <br />s
|
||
|
|
|
||
|
|
linebreaksbr
|
||
|
|
````````````
|
||
|
|
Converts newlines into <br />s
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
phone2numeric
|
||
|
|
`````````````
|
||
|
|
Takes a phone number and converts it in to its numerical equivalent
|
||
|
|
|
||
|
|
pluralize
|
||
|
|
`````````
|
||
|
|
Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'
|
||
|
|
|
||
|
|
pprint
|
||
|
|
``````
|
||
|
|
A wrapper around pprint.pprint -- for debugging, really
|
||
|
|
|
||
|
|
random
|
||
|
|
``````
|
||
|
|
Returns a random item from the list
|
||
|
|
|
||
|
|
removetags
|
||
|
|
```````````
|
||
|
|
Removes a space separated list of [X]HTML tags from the output
|
||
|
|
|
||
|
|
rjust
|
||
|
|
`````
|
||
|
|
Right-aligns the value in a field of a given width
|
||
|
|
|
||
|
|
Argument: field size
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
slugify
|
||
|
|
```````
|
||
|
|
Converts to lowercase, removes non-alpha chars and converts spaces to hyphens
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
striptags
|
||
|
|
`````````
|
||
|
|
Strips all [X]HTML tags
|
||
|
|
|
||
|
|
time
|
||
|
|
````
|
||
|
|
Formats a time according to the given format (same as the now_ tag).
|
||
|
|
|
||
|
|
timesince
|
||
|
|
`````````
|
||
|
|
Formats a date as the time since that date (i.e. "4 days, 6 hours")
|
||
|
|
|
||
|
|
title
|
||
|
|
`````
|
||
|
|
Converts a string into titlecase
|
||
|
|
|
||
|
|
truncatewords
|
||
|
|
`````````````
|
||
|
|
Truncates a string after a certain number of words
|
||
|
|
|
||
|
|
Argument: Number of words to truncate after
|
||
|
|
|
||
|
|
unordered_list
|
||
|
|
``````````````
|
||
|
|
Recursively takes a self-nested list and returns an HTML unordered list --
|
||
|
|
WITHOUT opening and closing <ul> tags.
|
||
|
|
|
||
|
|
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>
|
||
|
|
|
||
|
|
upper
|
||
|
|
`````
|
||
|
|
Converts a string into all uppercase
|
||
|
|
|
||
|
|
urlencode
|
||
|
|
`````````
|
||
|
|
Escapes a value for use in a URL
|
||
|
|
|
||
|
|
urlize
|
||
|
|
``````
|
||
|
|
Converts URLs in plain text into clickable links
|
||
|
|
|
||
|
|
urlizetrunc
|
||
|
|
```````````
|
||
|
|
Converts URLs into clickable links, truncating URLs to the given character limit
|
||
|
|
|
||
|
|
Argument: Length to truncate URLs to.
|
||
|
|
|
||
|
|
wordcount
|
||
|
|
`````````
|
||
|
|
Returns the number of words
|
||
|
|
|
||
|
|
wordwrap
|
||
|
|
````````
|
||
|
|
Wraps words at specified line length
|
||
|
|
|
||
|
|
Argument: number of words to wrap the text at.
|
||
|
|
|
||
|
|
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.
|
||
|
|
========== ====================== ==================================
|