+
−==================================
+
−Built-in template tags and filters
+
−==================================
+
−
+
−This document describes Django's built-in template tags and filters. It is
+
−recommended that you use the :doc:`automatic documentation
+
−</ref/contrib/admin/admindocs>`, if available, as this will also include
+
−documentation for any custom tags or filters installed.
+
−
+
−.. _ref-templates-builtins-tags:
+
−
+
−Built-in tag reference
+
−----------------------
+
−
+
−.. highlightlang:: html+django
+
−
+
−.. templatetag:: autoescape
+
−
+
−autoescape
+
−~~~~~~~~~~
+
−
+
−.. versionadded:: 1.0
+
−
+
−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. The block is closed with an ``endautoescape`` ending tag.
+
−
+
−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.
+
−
+
−Sample usage::
+
−
+
−    {% autoescape on %}
+
−        {{ body }}
+
−    {% endautoescape %}
+
−
+
−.. templatetag:: block
+
−
+
−block
+
−~~~~~
+
−
+
−Define a block that can be overridden by child templates. See
+
−:ref:`Template inheritance <template-inheritance>` for more information.
+
−
+
−.. templatetag:: comment
+
−
+
−comment
+
−~~~~~~~
+
−
+
−Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
+
−
+
−.. templatetag:: csrf_token
+
−
+
−csrf_token
+
−~~~~~~~~~~
+
−
+
−.. versionadded:: 1.1.2
+
−
+
−In the Django 1.1.X series, this is a no-op tag that returns an empty string for
+
−future compatibility purposes.  In Django 1.2 and later, it is used for CSRF
+
−protection, as described in the documentation for :doc:`Cross Site Request
+
−Forgeries </ref/contrib/csrf>`.
+
−
+
−.. templatetag:: cycle
+
−
+
−cycle
+
−~~~~~
+
−
+
−.. versionchanged:: 1.0
+
−    Cycle among the given strings or variables 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 %}
+
−
+
−You can use variables, too. For example, if you have two template variables,
+
−``rowvalue1`` and ``rowvalue2``, you can cycle between their values like this::
+
−
+
−    {% for o in some_list %}
+
−        <tr class="{% cycle rowvalue1 rowvalue2 %}">
+
−            ...
+
−        </tr>
+
−    {% endfor %}
+
−
+
−Yes, you can mix variables and strings::
+
−
+
−    {% for o in some_list %}
+
−        <tr class="{% cycle 'row1' rowvalue2 'row3' %}">
+
−            ...
+
−        </tr>
+
−    {% endfor %}
+
−
+
−In some cases you might want to refer to the next value of a cycle from
+
−outside of a loop. To do this, just give the ``{% cycle %}`` tag a name, using
+
−"as", like this::
+
−
+
−    {% cycle 'row1' 'row2' as rowcolors %}
+
−
+
−From then on, you can insert the current value of the cycle wherever you'd like
+
−in your template::
+
−
+
−    <tr class="{% cycle rowcolors %}">...</tr>
+
−    <tr class="{% cycle rowcolors %}">...</tr>
+
−
+
−You can use any number of values in a ``{% cycle %}`` tag, separated by spaces.
+
−Values enclosed in single (``'``) or double quotes (``"``) are treated as
+
−string literals, while values without quotes are treated as template variables.
+
−
+
−Note that the variables included in the cycle will not be escaped.
+
−This is because template tags do not escape their content. Any HTML or
+
−Javascript code contained in the printed variable will be rendered
+
−as-is, which could potentially lead to security issues.
+
−
+
−If you need to escape the variables in the cycle, you must do so
+
−explicitly::
+
−
+
−    {% filter force_escape %}
+
−        {% cycle var1 var2 var3 %}
+
−    {% endfilter %}
+
−
+
−For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior
+
−old syntax from previous Django versions. You shouldn't use this in any new
+
−projects, but for the sake of the people who are still using it, here's what it
+
−looks like::
+
−
+
−    {% cycle row1,row2,row3 %}
+
−
+
−In this syntax, each value gets interpreted as a literal string, and there's no
+
−way to specify variable values. Or literal commas. Or spaces. Did we mention
+
−you shouldn't use this syntax in any new projects?
+
−
+
−.. templatetag:: debug
+
−
+
−debug
+
−~~~~~
+
−
+
−Output a whole load of debugging information, including the current context and
+
−imported modules.
+
−
+
−.. templatetag:: extends
+
−
+
−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 :ref:`template-inheritance` for more information.
+
−
+
−.. templatetag:: filter
+
−
+
−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 %}
+
−
+
−.. templatetag:: firstof
+
−
+
−firstof
+
−~~~~~~~
+
−
+
−Outputs the first variable passed that is not False, without escaping.
+
−
+
−Outputs nothing if all the passed variables are False.
+
−
+
−Sample usage::
+
−
+
−    {% firstof var1 var2 var3 %}
+
−
+
−This is equivalent to::
+
−
+
−    {% if var1 %}
+
−        {{ var1|safe }}
+
−    {% else %}{% if var2 %}
+
−        {{ var2|safe }}
+
−    {% else %}{% if var3 %}
+
−        {{ var3|safe }}
+
−    {% 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" %}
+
−
+
−Note that the variables included in the firstof tag will not be
+
−escaped. This is because template tags do not escape their content.
+
−Any HTML or Javascript code contained in the printed variable will be
+
−rendered as-is, which could potentially lead to security issues.
+
−
+
−If you need to escape the variables in the firstof tag, you must do so
+
−explicitly::
+
−
+
−    {% filter force_escape %}
+
−        {% firstof var1 var2 var3 "fallback value" %}
+
−    {% endfilter %}
+
−
+
−.. templatetag:: for
+
−
+
−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 %}``.
+
−
+
−.. versionadded:: 1.0
+
−
+
−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
+
−    ==========================  ================================================
+
−
+
−for ... empty
+
−^^^^^^^^^^^^^
+
−
+
−.. versionadded:: 1.1
+
−
+
−The ``for`` tag can take an optional ``{% empty %}`` clause that will be
+
−displayed if the given array is empty or could not be found::
+
−
+
−    <ul>
+
−    {% for athlete in athlete_list %}
+
−        <li>{{ athlete.name }}</li>
+
−    {% empty %}
+
−        <li>Sorry, no athlete in this list!</li>
+
−    {% endfor %}
+
−    <ul>
+
−
+
−The above is equivalent to -- but shorter, cleaner, and possibly faster
+
−than -- the following::
+
−
+
−    <ul>
+
−      {% if athlete_list %}
+
−        {% for athlete in athlete_list %}
+
−          <li>{{ athlete.name }}</li>
+
−        {% endfor %}
+
−      {% else %}
+
−        <li>Sorry, no athletes in this list.</li>
+
−      {% endif %}
+
−    </ul>
+
−
+
−.. templatetag:: if
+
−
+
−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.
+
−
+
−Boolean operators
+
−^^^^^^^^^^^^^^^^^
+
−
+
−``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 %}
+
−
+
−.. versionchanged:: 1.2
+
−
+
−Use of both ``and`` and ``or`` clauses within the same tag is allowed, with
+
−``and`` having higher precedence than ``or`` e.g.::
+
−
+
−    {% if athlete_list and coach_list or cheerleader_list %}
+
−
+
−will be interpreted like:
+
−
+
−.. code-block:: python
+
−
+
−    if (athlete_list and coach_list) or cheerleader_list
+
−
+
−Use of actual brackets in the ``if`` tag is invalid syntax.  If you need them to
+
−indicate precedence, you should use nested ``if`` tags.
+
−
+
−.. versionadded:: 1.2
+
−
+
−
+
−``if`` tags may also use the operators ``==``, ``!=``, ``<``, ``>``,
+
−``<=``, ``>=`` and ``in`` which work as follows:
+
−
+
−
+
−``==`` operator
+
−^^^^^^^^^^^^^^^
+
−
+
−Equality. Example::
+
−
+
−    {% if somevar == "x" %}
+
−      This appears if variable somevar equals the string "x"
+
−    {% endif %}
+
−
+
−``!=`` operator
+
−^^^^^^^^^^^^^^^
+
−
+
−Inequality. Example::
+
−
+
−    {% if somevar != "x" %}
+
−      This appears if variable somevar does not equal the string "x",
+
−      or if somevar is not found in the context
+
−    {% endif %}
+
−
+
−``<`` operator
+
−^^^^^^^^^^^^^^
+
−
+
−Less than. Example::
+
−
+
−    {% if somevar < 100 %}
+
−      This appears if variable somevar is less than 100.
+
−    {% endif %}
+
−
+
−``>`` operator
+
−^^^^^^^^^^^^^^
+
−
+
−Greater than. Example::
+
−
+
−    {% if somevar > 0 %}
+
−      This appears if variable somevar is greater than 0.
+
−    {% endif %}
+
−
+
−``<=`` operator
+
−^^^^^^^^^^^^^^^
+
−
+
−Less than or equal to. Example::
+
−
+
−    {% if somevar <= 100 %}
+
−      This appears if variable somevar is less than 100 or equal to 100.
+
−    {% endif %}
+
−
+
−``>=`` operator
+
−^^^^^^^^^^^^^^^
+
−
+
−Greater than or equal to. Example::
+
−
+
−    {% if somevar >= 1 %}
+
−      This appears if variable somevar is greater than 1 or equal to 1.
+
−    {% endif %}
+
−
+
−``in`` operator
+
−^^^^^^^^^^^^^^^
+
−
+
−Contained within. This operator is supported by many Python containers to test
+
−whether the given value is in the container.  The following are some examples of
+
−how ``x in y`` will be interpreted::
+
−
+
−    {% if "bc" in "abcdef" %}
+
−      This appears since "bc" is a substring of "abcdef"
+
−    {% endif %}
+
−
+
−    {% if "hello" in greetings %}
+
−      If greetings is a list or set, one element of which is the string
+
−      "hello", this will appear.
+
−    {% endif %}
+
−
+
−    {% if user in users %}
+
−      If users is a QuerySet, this will appear if user is an
+
−      instance that belongs to the QuerySet.
+
−    {% endif %}
+
−
+
−``not in`` operator
+
−~~~~~~~~~~~~~~~~~~~~
+
−
+
−Not contained within.  This is the negation of the ``in`` operator.
+
−
+
−
+
−The comparison operators cannot be 'chained' like in Python or in mathematical
+
−notation. For example, instead of using::
+
−
+
−    {% if a > b > c %}  (WRONG)
+
−
+
−you should use::
+
−
+
−    {% if a > b and b > c %}
+
−
+
−
+
−Filters
+
−^^^^^^^
+
−
+
−You can also use filters in the ``if`` expression. For example::
+
−
+
−    {% if messages|length >= 100 %}
+
−       You have lots of messages today!
+
−    {% endif %}
+
−
+
−Complex expressions
+
−^^^^^^^^^^^^^^^^^^^
+
−
+
−All of the above can be combined to form complex expressions. For such
+
−expressions, it can be important to know how the operators are grouped when the
+
−expression is evaluated - that is, the precedence rules.  The precedence of the
+
−operators, from lowest to highest, is as follows:
+
−
+
− * ``or``
+
− * ``and``
+
− * ``not``
+
− * ``in``
+
− * ``==``, ``!=``, ``<``, ``>``,``<=``, ``>=``
+
−
+
−(This follows Python exactly). So, for example, the following complex if tag:
+
−
+
−    {% if a == b or c == d and e %}
+
−
+
−...will be interpreted as:
+
−
+
−.. code-block:: python
+
−
+
−    (a == b) or ((c == d) and e)
+
−
+
−If you need different precedence, you will need to use nested if tags. Sometimes
+
−that is better for clarity anyway, for the sake of those who do not know the
+
−precedence rules.
+
−
+
−
+
−.. templatetag:: ifchanged
+
−
+
−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 has changed::
+
−
+
−        {% for date in days %}
+
−            {% ifchanged date.date %} {{ date.date }} {% endifchanged %}
+
−            {% ifchanged date.hour date.date %}
+
−                {{ date.hour }}
+
−            {% endifchanged %}
+
−        {% endfor %}
+
−
+
−The ``ifchanged`` tag can also take 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 %}
+
−
+
−.. templatetag:: ifequal
+
−
+
−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.
+
−
+
−.. versionadded:: 1.2
+
−   An alternative to the ``ifequal`` tag is to use the :ttag:`if` tag and the ``==`` operator.
+
−
+
−.. templatetag:: ifnotequal
+
−
+
−ifnotequal
+
−~~~~~~~~~~
+
−
+
−Just like ``ifequal``, except it tests that the two arguments are not equal.
+
−
+
−.. versionadded:: 1.2
+
−   An alternative to the ``ifnotequal`` tag is to use the :ttag:`if` tag and the ``!=`` operator.
+
−
+
−.. templatetag:: include
+
−
+
−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 %}``.
+
−
+
−.. note::
+
−    The :ttag:`include` tag should be considered as an implementation of
+
−    "render this subtemplate and include the HTML", not as "parse this
+
−    subtemplate and include its contents as if it were part of the parent".
+
−    This means that there is no shared state between included templates --
+
−    each include is a completely independent rendering process.
+
−
+
−.. templatetag:: load
+
−
+
−load
+
−~~~~
+
−
+
−Load a custom template tag set.
+
−
+
−See :doc:`Custom tag and filter libraries </howto/custom-template-tags>` for more information.
+
−
+
−.. templatetag:: now
+
−
+
−now
+
−~~~
+
−
+
−Display the current date and/or time, according to the given string.
+
−
+
−Given format can be one of the predefined ones ``DATE_FORMAT``,
+
−``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``,
+
−or a custom format, same as the :tfilter:`date` filter. Note that predefined
+
−formats may vary depending on the current locale.
+
−
+
−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".
+
−
+
−.. templatetag:: regroup
+
−
+
−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:
+
−
+
−.. code-block:: python
+
−
+
−    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):
+
−
+
−.. code-block:: python
+
−
+
−    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 %}
+
−
+
−.. templatetag:: spaceless
+
−
+
−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 %}
+
−
+
−.. templatetag:: ssi
+
−
+
−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
+
−:setting:`ALLOWED_INCLUDE_ROOTS` in your Django settings, as a security measure.
+
−
+
−See also: ``{% include %}``.
+
−
+
−.. templatetag:: templatetag
+
−
+
−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``    ``#}``
+
−    ==================  =======
+
−
+
−.. templatetag:: url
+
−
+
−url
+
−~~~
+
−
+
−Returns an absolute path reference (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 v1 v2 %}
+
−
+
−The first argument is a path to a view function in the format
+
−``package.package.module.function``. Additional arguments are optional and
+
−should be space-separated values that will be used as arguments in the URL.
+
−The example above shows passing positional arguments. Alternatively you may
+
−use keyword syntax::
+
−
+
−    {% url path.to.some_view arg1=v1 arg2=v2 %}
+
−
+
−Do not mix both positional and keyword syntax in a single call. 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:
+
−
+
−.. code-block:: python
+
−
+
−    ('^client/(\d+)/$', 'app_views.client')
+
−
+
−If this app's URLconf is included into the project's URLconf under a path
+
−such as this:
+
−
+
−.. code-block:: python
+
−
+
−    ('^clients/', include('project_name.app_name.urls'))
+
−
+
−...then, in a template, you can create a link to this view like this::
+
−
+
−    {% url app_views.client client.id %}
+
−
+
−The template tag will output the string ``/clients/client/123/``.
+
−
+
−.. versionadded:: 1.0
+
−
+
−If you're using :ref:`named URL patterns <naming-url-patterns>`, you can
+
−refer to the name of the pattern in the ``url`` tag instead of using the
+
−path to the view.
+
−
+
−Note that if the URL you're reversing doesn't exist, you'll get an
+
−:exc:`NoReverseMatch` exception raised, which will cause your site to display an
+
−error page.
+
−
+
−.. versionadded:: 1.0
+
−
+
−If you'd like to retrieve a URL without displaying it, you can use a slightly
+
−different call::
+
−
+
−
+
−    {% url path.to.view arg arg2 as the_url %}
+
−
+
−    <a href="{{ the_url }}">I'm linking to {{ the_url }}</a>
+
−
+
−This ``{% url ... as var %}`` syntax will *not* cause an error if the view is
+
−missing. In practice you'll use this to link to views that are optional::
+
−
+
−    {% url path.to.view as the_url %}
+
−    {% if the_url %}
+
−      <a href="{{ the_url }}">Link to optional stuff</a>
+
−    {% endif %}
+
−
+
−.. versionadded:: 1.1
+
−
+
−If you'd like to retrieve a namespaced URL, specify the fully qualified name::
+
−
+
−    {% url myapp:view-name %}
+
−
+
−This will follow the normal :ref:`namespaced URL resolution strategy
+
−<topics-http-reversing-url-namespaces>`, including using any hints provided
+
−by the context as to the current application.
+
−
+
−.. versionchanged:: 1.2
+
−
+
−For backwards compatibility, the ``{% url %}`` tag also supports the
+
−use of commas to separate arguments. You shouldn't use this in any new
+
−projects, but for the sake of the people who are still using it,
+
−here's what it looks like::
+
−
+
−    {% url path.to.view arg,arg2 %}
+
−    {% url path.to.view arg, arg2 %}
+
−
+
−This syntax doesn't support the use of literal commas, or or equals
+
−signs. Did we mention you shouldn't use this syntax in any new
+
−projects?
+
−
+
−.. templatetag:: widthratio
+
−
+
−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 image in the
+
−above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5
+
−which is rounded up to 88).
+
−
+
−.. templatetag:: with
+
−
+
−with
+
−~~~~
+
−
+
−.. versionadded:: 1.0
+
−
+
−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.
+
−
+
−.. _ref-templates-builtins-filters:
+
−
+
−Built-in filter reference
+
−-------------------------
+
−
+
−.. templatefilter:: add
+
−
+
−add
+
−~~~
+
−
+
−Adds the argument to the value.
+
−
+
−For example::
+
−
+
−    {{ value|add:"2" }}
+
−
+
−If ``value`` is ``4``, then the output will be ``6``.
+
−
+
−.. versionchanged:: 1.2
+
−   The following behavior didn't exist in previous Django versions.
+
−
+
−This filter will first try to coerce both values to integers. If this fails,
+
−it'll attempt to add the values together anyway. This will work on some data
+
−types (strings, list, etc.) and fail on others. If it fails, the result will
+
−be an empty string.
+
−
+
−For example, if we have::
+
−
+
−    {{ first|add:second }}
+
−
+
−and ``first`` is ``[1, 2, 3]`` and ``second`` is ``[4, 5, 6]``, then the
+
−output will be ``[1, 2, 3, 4, 5, 6]``.
+
−
+
−.. warning::
+
−
+
−    Strings that can be coerced to integers will be **summed**, not
+
−    concatenated, as in the first example above.
+
−
+
−.. templatefilter:: addslashes
+
−
+
−addslashes
+
−~~~~~~~~~~
+
−
+
−Adds slashes before quotes. Useful for escaping strings in CSV, for example.
+
−
+
−For example::
+
−
+
−    {{ value|addslashes }}
+
−
+
−If ``value`` is ``"I'm using Django"``, the output will be ``"I\'m using Django"``.
+
−
+
−.. templatefilter:: capfirst
+
−
+
−capfirst
+
−~~~~~~~~
+
−
+
−Capitalizes the first character of the value.
+
−
+
−For example::
+
−
+
−    {{ value|capfirst }}
+
−
+
−If ``value`` is ``"django"``, the output will be ``"Django"``.
+
−
+
−.. templatefilter:: center
+
−
+
−center
+
−~~~~~~
+
−
+
−Centers the value in a field of a given width.
+
−
+
−For example::
+
−
+
−    "{{ value|center:"15" }}"
+
−
+
−If ``value`` is ``"Django"``, the output will be ``"     Django    "``.
+
−
+
−.. templatefilter:: cut
+
−
+
−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"``.
+
−
+
−.. templatefilter:: date
+
−
+
−date
+
−~~~~
+
−
+
−Formats a date according to the given format.
+
−
+
−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.
+
−    c                 ISO 8601 Format.                          ``2008-01-02T10:30:00.000123``
+
−    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                 Microseconds.                             ``0`` to ``999999``
+
−    U                 Seconds since the Unix Epoch
+
−                      (January 1 1970 00:00:00 UTC).
+
−    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.
+
−    ================  ========================================  =====================
+
−
+
−.. versionadded:: 1.2
+
−
+
−The ``c`` and ``u`` format specification characters were added in Django 1.2.
+
−
+
−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'``.
+
−
+
−The format passed can be one of the predefined ones ``DATE_FORMAT``,
+
−``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, or a
+
−custom format that uses the format specifiers shown in the table above. Note
+
−that predefined formats may vary depending on the current locale.
+
−
+
−Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is,
+
−for example, ``"es"``, then for::
+
−
+
−    {{ value|date:"SHORT_DATE_FORMAT" }}
+
−
+
−the output would be the string ``"09/01/2008"`` (the ``"SHORT_DATE_FORMAT"``
+
−format specifier for the ``es`` locale as shipped with Django is ``"d/m/Y"``).
+
−
+
−When used without a format string::
+
−
+
−    {{ value|date }}
+
−
+
−...the formatting string defined in the :setting:`DATE_FORMAT` setting will be
+
−used, without applying any localization.
+
−
+
−.. versionchanged:: 1.2
+
−    Predefined formats can now be influenced by the current locale.
+
−
+
−.. templatefilter:: default
+
−
+
−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``.
+
−
+
−.. templatefilter:: default_if_none
+
−
+
−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"``.
+
−
+
−.. templatefilter:: dictsort
+
−
+
−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:
+
−
+
−.. code-block:: python
+
−
+
−    [
+
−        {'name': 'zed', 'age': 19},
+
−        {'name': 'amy', 'age': 22},
+
−        {'name': 'joe', 'age': 31},
+
−    ]
+
−
+
−then the output would be:
+
−
+
−.. code-block:: python
+
−
+
−    [
+
−        {'name': 'amy', 'age': 22},
+
−        {'name': 'joe', 'age': 31},
+
−        {'name': 'zed', 'age': 19},
+
−    ]
+
−
+
−.. templatefilter:: dictsortreversed
+
−
+
−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.
+
−
+
−.. templatefilter:: divisibleby
+
−
+
−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``.
+
−
+
−.. templatefilter:: escape
+
−
+
−escape
+
−~~~~~~
+
−
+
−Escapes a string's HTML. Specifically, it makes these replacements:
+
−
+
−    * ``<`` is converted to ``&lt;``
+
−    * ``>`` is converted to ``&gt;``
+
−    * ``'`` (single quote) is converted to ``&#39;``
+
−    * ``"`` (double quote) is converted to ``&quot;``
+
−    * ``&`` is converted to ``&amp;``
+
−
+
−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.
+
−
+
−.. versionchanged:: 1.0
+
−    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.
+
−
+
−.. templatefilter:: escapejs
+
−
+
−escapejs
+
−~~~~~~~~
+
−
+
−.. versionadded:: 1.0
+
−
+
−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.
+
−
+
−For example::
+
−
+
−    {{ value|escapejs }}
+
−
+
−If ``value`` is ``"testing\r\njavascript \'string" <b>escaping</b>"``,
+
−the output will be ``"testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u003Cb\\u003Eescaping\\u003C/b\\u003E"``.
+
−
+
−.. templatefilter:: filesizeformat
+
−
+
−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``.
+
−
+
−.. templatefilter:: first
+
−
+
−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'``.
+
−
+
−.. templatefilter:: fix_ampersands
+
−
+
−fix_ampersands
+
−~~~~~~~~~~~~~~
+
−
+
−.. versionchanged:: 1.0
+
−    This is rarely useful as ampersands are now automatically escaped. See escape_ for more information.
+
−
+
−Replaces ampersands with ``&amp;`` entities.
+
−
+
−For example::
+
−
+
−    {{ value|fix_ampersands }}
+
−
+
−If ``value`` is ``Tom & Jerry``, the output will be ``Tom &amp; Jerry``.
+
−
+
−.. templatefilter:: floatformat
+
−
+
−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``.
+
−
+
−.. templatefilter:: force_escape
+
−
+
−force_escape
+
−~~~~~~~~~~~~
+
−
+
−.. versionadded:: 1.0
+
−
+
−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.
+
−
+
−.. templatefilter:: get_digit
+
−
+
−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``.
+
−
+
−.. templatefilter:: iriencode
+
−
+
−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.
+
−
+
−For example::
+
−
+
−    {{ value|iriencode }}
+
−
+
−If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&amp;me=2"``.
+
−
+
−.. templatefilter:: join
+
−
+
−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"``.
+
−
+
−.. templatefilter:: last
+
−
+
−last
+
−~~~~
+
−
+
−.. versionadded:: 1.0
+
−
+
−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"``.
+
−
+
−.. templatefilter:: length
+
−
+
−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``.
+
−
+
−.. templatefilter:: length_is
+
−
+
−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``.
+
−
+
−.. templatefilter:: linebreaks
+
−
+
−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>``.
+
−
+
−.. templatefilter:: linebreaksbr
+
−
+
−linebreaksbr
+
−~~~~~~~~~~~~
+
−
+
−Converts all newlines in a piece of plain text to HTML line breaks
+
−(``<br />``).
+
−
+
−For example::
+
−
+
−    {{ value|linebreaksbr }}
+
−
+
−If ``value`` is ``Joel\nis a slug``, the output will be ``Joel<br />is a
+
−slug``.
+
−
+
−.. templatefilter:: linenumbers
+
−
+
−linenumbers
+
−~~~~~~~~~~~
+
−
+
−Displays text with line numbers.
+
−
+
−For example::
+
−
+
−    {{ value|linenumbers }}
+
−
+
−If ``value`` is::
+
−
+
−    one
+
−    two
+
−    three
+
−
+
−the output will be::
+
−
+
−    1. one
+
−    2. two
+
−    3. three
+
−
+
−.. templatefilter:: ljust
+
−
+
−ljust
+
−~~~~~
+
−
+
−Left-aligns the value in a field of a given width.
+
−
+
−**Argument:** field size
+
−
+
−For example::
+
−
+
−    "{{ value|ljust:"10" }}"
+
−
+
−If ``value`` is ``Django``, the output will be ``"Django    "``.
+
−
+
−.. templatefilter:: lower
+
−
+
−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``.
+
−
+
−.. templatefilter:: make_list
+
−
+
−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]``.
+
−
+
−.. templatefilter:: phone2numeric
+
−
+
−phone2numeric
+
−~~~~~~~~~~~~~
+
−
+
−Converts a phone number (possibly containing letters) to its numerical
+
−equivalent.
+
−
+
−The input doesn't have to be a valid phone number. This will happily convert
+
−any string.
+
−
+
−For example::
+
−
+
−    {{ value|phone2numeric }}
+
−
+
−If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``.
+
−
+
−.. templatefilter:: pluralize
+
−
+
−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 }}.
+
−
+
−If ``num_messages`` is ``1``, the output will be ``You have 1 message.``
+
−If ``num_messages`` is ``2``  the output will be ``You have 2 messages.``
+
−
+
−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_walruses|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" }}.
+
−
+
−.. templatefilter:: pprint
+
−
+
−pprint
+
−~~~~~~
+
−
+
−A wrapper around `pprint.pprint`__ -- for debugging, really.
+
−
+
−__ http://docs.python.org/library/pprint.html
+
−
+
−.. templatefilter:: random
+
−
+
−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"``.
+
−
+
−.. templatefilter:: removetags
+
−
+
−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"``.
+
−
+
−Note that this filter is case-sensitive.
+
−
+
−If ``value`` is ``"<B>Joel</B> <button>is</button> a <span>slug</span>"`` the
+
−output will be ``"<B>Joel</B> <button>is</button> a slug"``.
+
−
+
−.. templatefilter:: rjust
+
−
+
−rjust
+
−~~~~~
+
−
+
−Right-aligns the value in a field of a given width.
+
−
+
−**Argument:** field size
+
−
+
−For example::
+
−
+
−    "{{ value|rjust:"10" }}"
+
−
+
−If ``value`` is ``Django``, the output will be ``"    Django"``.
+
−
+
−.. templatefilter:: safe
+
−
+
−safe
+
−~~~~
+
−
+
−Marks a string as not requiring further HTML escaping prior to output. When
+
−autoescaping is off, this filter has no effect.
+
−
+
−.. note::
+
−
+
−    If you are chaining filters, a filter applied after ``safe`` can
+
−    make the contents unsafe again. For example, the following code
+
−    prints the variable as is, unescaped:
+
−
+
−    .. code-block:: html+django
+
−
+
−        {{ var|safe|escape }}
+
−
+
−.. templatefilter:: safeseq
+
−
+
−safeseq
+
−~~~~~~~
+
−
+
−Applies the :tfilter:`safe` filter to each element of a sequence.  Useful in
+
−conjunction with other filters that operate on sequences, such as
+
−:tfilter:`join`.  For example::
+
−
+
−    {{ some_list|safeseq|join:", " }}
+
−
+
−You couldn't use the :tfilter:`safe` filter directly in this case, as it would
+
−first convert the variable into a string, rather than working with the
+
−individual elements of the sequence.
+
−
+
−.. templatefilter:: slice
+
−
+
−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" }}
+
−
+
−If ``some_list`` is ``['a', 'b', 'c']``, the output will be ``['a', 'b']``.
+
−
+
−.. templatefilter:: slugify
+
−
+
−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"``.
+
−
+
−.. templatefilter:: stringformat
+
−
+
−stringformat
+
−~~~~~~~~~~~~
+
−
+
−Formats the variable according to the argument, a string formatting specifier.
+
−This specifier uses Python string formatting syntax, with the exception that
+
−the leading "%" is dropped.
+
−
+
−See http://docs.python.org/library/stdtypes.html#string-formatting-operations
+
−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"``.
+
−
+
−.. templatefilter:: striptags
+
−
+
−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"``.
+
−
+
−.. templatefilter:: time
+
−
+
−time
+
−~~~~
+
−
+
−Formats a time according to the given format.
+
−
+
−Given format can be the predefined one ``TIME_FORMAT``, or a custom format,
+
−same as the :tfilter:`date` filter. Note that the predefined format is locale-
+
−dependant.
+
−
+
−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 :tfilter:`date` filter.
+
−
+
−For example::
+
−
+
−    {{ value|time:"H:i" }}
+
−
+
−If ``value`` is equivalent to ``datetime.datetime.now()``, the output will be
+
−the string ``"01:23"``.
+
−
+
−Another example:
+
−
+
−Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is,
+
−for example, ``"de"``, then for::
+
−
+
−    {{ value|time:"TIME_FORMAT" }}
+
−
+
−the output will be the string ``"01:23:00"`` (The ``"TIME_FORMAT"`` format
+
−specifier for the ``de`` locale as shipped with Django is ``"H:i:s"``).
+
−
+
−When used without a format string::
+
−
+
−    {{ value|time }}
+
−
+
−...the formatting string defined in the :setting:`TIME_FORMAT` setting will be
+
−used, without applying any localization.
+
−
+
−.. versionchanged:: 1.2
+
−    Predefined formats can now be influenced by the current locale.
+
−
+
−.. templatefilter:: timesince
+
−
+
−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 ``{{ blog_date|timesince:comment_date }}`` would return "8 hours".
+
−
+
−Comparing offset-naive and offset-aware datetimes will return an empty string.
+
−
+
−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.
+
−
+
−.. templatefilter:: timeuntil
+
−
+
−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".
+
−
+
−Comparing offset-naive and offset-aware datetimes will return an empty string.
+
−
+
−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.
+
−
+
−.. templatefilter:: title
+
−
+
−title
+
−~~~~~
+
−
+
−Converts a string into titlecase.
+
−
+
−For example::
+
−
+
−    {{ value|title }}
+
−
+
−If ``value`` is ``"my first post"``, the output will be ``"My First Post"``.
+
−
+
−.. templatefilter:: truncatewords
+
−
+
−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 ..."``.
+
−
+
−Newlines within the string will be removed.
+
−
+
−.. templatefilter:: truncatewords_html
+
−
+
−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.
+
−
+
−For example::
+
−
+
−    {{ value|truncatewords_html:2 }}
+
−
+
−If ``value`` is ``"<p>Joel is a slug</p>"``, the output will be
+
−``"<p>Joel is ...</p>"``.
+
−
+
−Newlines in the HTML content will be preserved.
+
−
+
−.. templatefilter:: unordered_list
+
−
+
−unordered_list
+
−~~~~~~~~~~~~~~
+
−
+
−Recursively takes a self-nested list and returns an HTML unordered list --
+
−WITHOUT opening and closing <ul> tags.
+
−
+
−.. versionchanged:: 1.0
+
−   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', []]]]``,
+
−
+
−.. templatefilter:: upper
+
−
+
−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"``.
+
−
+
−.. templatefilter:: urlencode
+
−
+
−urlencode
+
−~~~~~~~~~
+
−
+
−Escapes a value for use in a URL.
+
−
+
−For example::
+
−
+
−    {{ value|urlencode }}
+
−
+
−If ``value`` is ``"http://www.example.org/foo?a=b&c=d"``, the output will be
+
−``"http%3A//www.example.org/foo%3Fa%3Db%26c%3Dd"``.
+
−
+
−.. templatefilter:: urlize
+
−
+
−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>"``.
+
−
+
−.. templatefilter:: urlizetrunc
+
−
+
−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>'``.
+
−
+
−.. templatefilter:: wordcount
+
−
+
−wordcount
+
−~~~~~~~~~
+
−
+
−Returns the number of words.
+
−
+
−For example::
+
−
+
−    {{ value|wordcount }}
+
−
+
−If ``value`` is ``"Joel is a slug"``, the output will be ``4``.
+
−
+
−.. templatefilter:: wordwrap
+
−
+
−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
+
−
+
−.. templatefilter:: yesno
+
−
+
−yesno
+
−~~~~~
+
−
+
−Given a string mapping values for true, false and (optionally) None,
+
−returns one of those strings according to the value:
+
−
+
−For example::
+
−
+
−    {{ value|yesno:"yeah,no,maybe" }}
+
−
+
−==========  ======================  ==================================
+
−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
+
−:doc:`/ref/contrib/humanize`.
+
−
+
−django.contrib.markup
+
−~~~~~~~~~~~~~~~~~~~~~
+
−
+
−A collection of template filters that implement these common markup languages:
+
−
+
−    * Textile
+
−    * Markdown
+
−    * reST (reStructuredText)
+
−
+
−See the :doc:`markup documentation </ref/contrib/markup>`.
+
−
+
−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 :doc:`/ref/contrib/webdesign`.
+
−
+
−i18n
+
−~~~~
+
−
+
−Provides a couple of templatetags that allow specifying translatable text in
+
−Django templates. It is slightly different from the libraries described
+
−above because you don't need to add any application to the ``INSTALLED_APPS``
+
−setting but rather set :setting:`USE_I18N` to True, then loading it with
+
−``{% load i18n %}``. See :ref:`specifying-translation-strings-in-template-code`.