1 ==================================

     2 Built-in template tags and filters

     3 ==================================

     4 

     5 This document describes Django's built-in template tags and filters. It is

     6 recommended that you use the :doc:`automatic documentation

     7 </ref/contrib/admin/admindocs>`, if available, as this will also include

     8 documentation for any custom tags or filters installed.

     9 

    10 .. _ref-templates-builtins-tags:

    11 

    12 Built-in tag reference

    13 ----------------------

    14 

    15 .. highlightlang:: html+django

    16 

    17 .. templatetag:: autoescape

    18 

    19 autoescape

    20 ~~~~~~~~~~

    21 

    22 .. versionadded:: 1.0

    23 

    24 Control the current auto-escaping behavior. This tag takes either ``on`` or

    25 ``off`` as an argument and that determines whether auto-escaping is in effect

    26 inside the block. The block is closed with an ``endautoescape`` ending tag.

    27 

    28 When auto-escaping is in effect, all variable content has HTML escaping applied

    29 to it before placing the result into the output (but after any filters have

    30 been applied). This is equivalent to manually applying the ``escape`` filter

    31 to each variable.

    32 

    33 The only exceptions are variables that are already marked as "safe" from

    34 escaping, either by the code that populated the variable, or because it has had

    35 the ``safe`` or ``escape`` filters applied.

    36 

    37 Sample usage::

    38 

    39     {% autoescape on %}

    40         {{ body }}

    41     {% endautoescape %}

    42 

    43 .. templatetag:: block

    44 

    45 block

    46 ~~~~~

    47 

    48 Define a block that can be overridden by child templates. See

    49 :ref:`Template inheritance <template-inheritance>` for more information.

    50 

    51 .. templatetag:: comment

    52 

    53 comment

    54 ~~~~~~~

    55 

    56 Ignore everything between ``{% comment %}`` and ``{% endcomment %}``

    57 

    58 .. templatetag:: csrf_token

    59 

    60 csrf_token

    61 ~~~~~~~~~~

    62 

    63 .. versionadded:: 1.1.2

    64 

    65 In the Django 1.1.X series, this is a no-op tag that returns an empty string for

    66 future compatibility purposes.  In Django 1.2 and later, it is used for CSRF

    67 protection, as described in the documentation for :doc:`Cross Site Request

    68 Forgeries </ref/contrib/csrf>`.

    69 

    70 .. templatetag:: cycle

    71 

    72 cycle

    73 ~~~~~

    74 

    75 .. versionchanged:: 1.0

    76     Cycle among the given strings or variables each time this tag is encountered.

    77 

    78 Within a loop, cycles among the given strings each time through the

    79 loop::

    80 

    81     {% for o in some_list %}

    82         <tr class="{% cycle 'row1' 'row2' %}">

    83             ...

    84         </tr>

    85     {% endfor %}

    86 

    87 You can use variables, too. For example, if you have two template variables,

    88 ``rowvalue1`` and ``rowvalue2``, you can cycle between their values like this::

    89 

    90     {% for o in some_list %}

    91         <tr class="{% cycle rowvalue1 rowvalue2 %}">

    92             ...

    93         </tr>

    94     {% endfor %}

    95 

    96 Yes, you can mix variables and strings::

    97 

    98     {% for o in some_list %}

    99         <tr class="{% cycle 'row1' rowvalue2 'row3' %}">

   100             ...

   101         </tr>

   102     {% endfor %}

   103 

   104 In some cases you might want to refer to the next value of a cycle from

   105 outside of a loop. To do this, just give the ``{% cycle %}`` tag a name, using

   106 "as", like this::

   107 

   108     {% cycle 'row1' 'row2' as rowcolors %}

   109 

   110 From then on, you can insert the current value of the cycle wherever you'd like

   111 in your template::

   112 

   113     <tr class="{% cycle rowcolors %}">...</tr>

   114     <tr class="{% cycle rowcolors %}">...</tr>

   115 

   116 You can use any number of values in a ``{% cycle %}`` tag, separated by spaces.

   117 Values enclosed in single (``'``) or double quotes (``"``) are treated as

   118 string literals, while values without quotes are treated as template variables.

   119 

   120 Note that the variables included in the cycle will not be escaped.

   121 This is because template tags do not escape their content. Any HTML or

   122 Javascript code contained in the printed variable will be rendered

   123 as-is, which could potentially lead to security issues.

   124 

   125 If you need to escape the variables in the cycle, you must do so

   126 explicitly::

   127 

   128     {% filter force_escape %}

   129         {% cycle var1 var2 var3 %}

   130     {% endfilter %}

   131 

   132 For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior

   133 old syntax from previous Django versions. You shouldn't use this in any new

   134 projects, but for the sake of the people who are still using it, here's what it

   135 looks like::

   136 

   137     {% cycle row1,row2,row3 %}

   138 

   139 In this syntax, each value gets interpreted as a literal string, and there's no

   140 way to specify variable values. Or literal commas. Or spaces. Did we mention

   141 you shouldn't use this syntax in any new projects?

   142 

   143 .. templatetag:: debug

   144 

   145 debug

   146 ~~~~~

   147 

   148 Output a whole load of debugging information, including the current context and

   149 imported modules.

   150 

   151 .. templatetag:: extends

   152 

   153 extends

   154 ~~~~~~~

   155 

   156 Signal that this template extends a parent template.

   157 

   158 This tag can be used in two ways:

   159 

   160    * ``{% extends "base.html" %}`` (with quotes) uses the literal value

   161      ``"base.html"`` as the name of the parent template to extend.

   162 

   163    * ``{% extends variable %}`` uses the value of ``variable``. If the variable

   164      evaluates to a string, Django will use that string as the name of the

   165      parent template. If the variable evaluates to a ``Template`` object,

   166      Django will use that object as the parent template.

   167 

   168 See :ref:`template-inheritance` for more information.

   169 

   170 .. templatetag:: filter

   171 

   172 filter

   173 ~~~~~~

   174 

   175 Filter the contents of the variable through variable filters.

   176 

   177 Filters can also be piped through each other, and they can have arguments --

   178 just like in variable syntax.

   179 

   180 Sample usage::

   181 

   182     {% filter force_escape|lower %}

   183         This text will be HTML-escaped, and will appear in all lowercase.

   184     {% endfilter %}

   185 

   186 .. templatetag:: firstof

   187 

   188 firstof

   189 ~~~~~~~

   190 

   191 Outputs the first variable passed that is not False, without escaping.

   192 

   193 Outputs nothing if all the passed variables are False.

   194 

   195 Sample usage::

   196 

   197     {% firstof var1 var2 var3 %}

   198 

   199 This is equivalent to::

   200 

   201     {% if var1 %}

   202         {{ var1|safe }}

   203     {% else %}{% if var2 %}

   204         {{ var2|safe }}

   205     {% else %}{% if var3 %}

   206         {{ var3|safe }}

   207     {% endif %}{% endif %}{% endif %}

   208 

   209 You can also use a literal string as a fallback value in case all

   210 passed variables are False::

   211 

   212     {% firstof var1 var2 var3 "fallback value" %}

   213 

   214 Note that the variables included in the firstof tag will not be

   215 escaped. This is because template tags do not escape their content.

   216 Any HTML or Javascript code contained in the printed variable will be

   217 rendered as-is, which could potentially lead to security issues.

   218 

   219 If you need to escape the variables in the firstof tag, you must do so

   220 explicitly::

   221 

   222     {% filter force_escape %}

   223         {% firstof var1 var2 var3 "fallback value" %}

   224     {% endfilter %}

   225 

   226 .. templatetag:: for

   227 

   228 for

   229 ~~~

   230 

   231 Loop over each item in an array.  For example, to display a list of athletes

   232 provided in ``athlete_list``::

   233 

   234     <ul>

   235     {% for athlete in athlete_list %}

   236         <li>{{ athlete.name }}</li>

   237     {% endfor %}

   238     </ul>

   239 

   240 You can loop over a list in reverse by using ``{% for obj in list reversed %}``.

   241 

   242 .. versionadded:: 1.0

   243 

   244 If you need to loop over a list of lists, you can unpack the values

   245 in each sub-list into individual variables. For example, if your context

   246 contains a list of (x,y) coordinates called ``points``, you could use the

   247 following to output the list of points::

   248 

   249     {% for x, y in points %}

   250         There is a point at {{ x }},{{ y }}

   251     {% endfor %}

   252 

   253 This can also be useful if you need to access the items in a dictionary.

   254 For example, if your context contained a dictionary ``data``, the following

   255 would display the keys and values of the dictionary::

   256 

   257     {% for key, value in data.items %}

   258         {{ key }}: {{ value }}

   259     {% endfor %}

   260 

   261 The for loop sets a number of variables available within the loop:

   262 

   263     ==========================  ================================================

   264     Variable                    Description

   265     ==========================  ================================================

   266     ``forloop.counter``         The current iteration of the loop (1-indexed)

   267     ``forloop.counter0``        The current iteration of the loop (0-indexed)

   268     ``forloop.revcounter``      The number of iterations from the end of the

   269                                 loop (1-indexed)

   270     ``forloop.revcounter0``     The number of iterations from the end of the

   271                                 loop (0-indexed)

   272     ``forloop.first``           True if this is the first time through the loop

   273     ``forloop.last``            True if this is the last time through the loop

   274     ``forloop.parentloop``      For nested loops, this is the loop "above" the

   275                                 current one

   276     ==========================  ================================================

   277 

   278 for ... empty

   279 ^^^^^^^^^^^^^

   280 

   281 .. versionadded:: 1.1

   282 

   283 The ``for`` tag can take an optional ``{% empty %}`` clause that will be

   284 displayed if the given array is empty or could not be found::

   285 

   286     <ul>

   287     {% for athlete in athlete_list %}

   288         <li>{{ athlete.name }}</li>

   289     {% empty %}

   290         <li>Sorry, no athlete in this list!</li>

   291     {% endfor %}

   292     <ul>

   293 

   294 The above is equivalent to -- but shorter, cleaner, and possibly faster

   295 than -- the following::

   296 

   297     <ul>

   298       {% if athlete_list %}

   299         {% for athlete in athlete_list %}

   300           <li>{{ athlete.name }}</li>

   301         {% endfor %}

   302       {% else %}

   303         <li>Sorry, no athletes in this list.</li>

   304       {% endif %}

   305     </ul>

   306 

   307 .. templatetag:: if

   308 

   309 if

   310 ~~

   311 

   312 The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.

   313 exists, is not empty, and is not a false boolean value) the contents of the

   314 block are output::

   315 

   316     {% if athlete_list %}

   317         Number of athletes: {{ athlete_list|length }}

   318     {% else %}

   319         No athletes.

   320     {% endif %}

   321 

   322 In the above, if ``athlete_list`` is not empty, the number of athletes will be

   323 displayed by the ``{{ athlete_list|length }}`` variable.

   324 

   325 As you can see, the ``if`` tag can take an optional ``{% else %}`` clause that

   326 will be displayed if the test fails.

   327 

   328 Boolean operators

   329 ^^^^^^^^^^^^^^^^^

   330 

   331 ``if`` tags may use ``and``, ``or`` or ``not`` to test a number of variables or

   332 to negate a given variable::

   333 

   334     {% if athlete_list and coach_list %}

   335         Both athletes and coaches are available.

   336     {% endif %}

   337 

   338     {% if not athlete_list %}

   339         There are no athletes.

   340     {% endif %}

   341 

   342     {% if athlete_list or coach_list %}

   343         There are some athletes or some coaches.

   344     {% endif %}

   345 

   346     {% if not athlete_list or coach_list %}

   347         There are no athletes or there are some coaches (OK, so

   348         writing English translations of boolean logic sounds

   349         stupid; it's not our fault).

   350     {% endif %}

   351 

   352     {% if athlete_list and not coach_list %}

   353         There are some athletes and absolutely no coaches.

   354     {% endif %}

   355 

   356 .. versionchanged:: 1.2

   357 

   358 Use of both ``and`` and ``or`` clauses within the same tag is allowed, with

   359 ``and`` having higher precedence than ``or`` e.g.::

   360 

   361     {% if athlete_list and coach_list or cheerleader_list %}

   362 

   363 will be interpreted like:

   364 

   365 .. code-block:: python

   366 

   367     if (athlete_list and coach_list) or cheerleader_list

   368 

   369 Use of actual brackets in the ``if`` tag is invalid syntax.  If you need them to

   370 indicate precedence, you should use nested ``if`` tags.

   371 

   372 .. versionadded:: 1.2

   373 

   374 

   375 ``if`` tags may also use the operators ``==``, ``!=``, ``<``, ``>``,

   376 ``<=``, ``>=`` and ``in`` which work as follows:

   377 

   378 

   379 ``==`` operator

   380 ^^^^^^^^^^^^^^^

   381 

   382 Equality. Example::

   383 

   384     {% if somevar == "x" %}

   385       This appears if variable somevar equals the string "x"

   386     {% endif %}

   387 

   388 ``!=`` operator

   389 ^^^^^^^^^^^^^^^

   390 

   391 Inequality. Example::

   392 

   393     {% if somevar != "x" %}

   394       This appears if variable somevar does not equal the string "x",

   395       or if somevar is not found in the context

   396     {% endif %}

   397 

   398 ``<`` operator

   399 ^^^^^^^^^^^^^^

   400 

   401 Less than. Example::

   402 

   403     {% if somevar < 100 %}

   404       This appears if variable somevar is less than 100.

   405     {% endif %}

   406 

   407 ``>`` operator

   408 ^^^^^^^^^^^^^^

   409 

   410 Greater than. Example::

   411 

   412     {% if somevar > 0 %}

   413       This appears if variable somevar is greater than 0.

   414     {% endif %}

   415 

   416 ``<=`` operator

   417 ^^^^^^^^^^^^^^^

   418 

   419 Less than or equal to. Example::

   420 

   421     {% if somevar <= 100 %}

   422       This appears if variable somevar is less than 100 or equal to 100.

   423     {% endif %}

   424 

   425 ``>=`` operator

   426 ^^^^^^^^^^^^^^^

   427 

   428 Greater than or equal to. Example::

   429 

   430     {% if somevar >= 1 %}

   431       This appears if variable somevar is greater than 1 or equal to 1.

   432     {% endif %}

   433 

   434 ``in`` operator

   435 ^^^^^^^^^^^^^^^

   436 

   437 Contained within. This operator is supported by many Python containers to test

   438 whether the given value is in the container.  The following are some examples of

   439 how ``x in y`` will be interpreted::

   440 

   441     {% if "bc" in "abcdef" %}

   442       This appears since "bc" is a substring of "abcdef"

   443     {% endif %}

   444 

   445     {% if "hello" in greetings %}

   446       If greetings is a list or set, one element of which is the string

   447       "hello", this will appear.

   448     {% endif %}

   449 

   450     {% if user in users %}

   451       If users is a QuerySet, this will appear if user is an

   452       instance that belongs to the QuerySet.

   453     {% endif %}

   454 

   455 ``not in`` operator

   456 ~~~~~~~~~~~~~~~~~~~~

   457 

   458 Not contained within.  This is the negation of the ``in`` operator.

   459 

   460 

   461 The comparison operators cannot be 'chained' like in Python or in mathematical

   462 notation. For example, instead of using::

   463 

   464     {% if a > b > c %}  (WRONG)

   465 

   466 you should use::

   467 

   468     {% if a > b and b > c %}

   469 

   470 

   471 Filters

   472 ^^^^^^^

   473 

   474 You can also use filters in the ``if`` expression. For example::

   475 

   476     {% if messages|length >= 100 %}

   477        You have lots of messages today!

   478     {% endif %}

   479 

   480 Complex expressions

   481 ^^^^^^^^^^^^^^^^^^^

   482 

   483 All of the above can be combined to form complex expressions. For such

   484 expressions, it can be important to know how the operators are grouped when the

   485 expression is evaluated - that is, the precedence rules.  The precedence of the

   486 operators, from lowest to highest, is as follows:

   487 

   488  * ``or``

   489  * ``and``

   490  * ``not``

   491  * ``in``

   492  * ``==``, ``!=``, ``<``, ``>``,``<=``, ``>=``

   493 

   494 (This follows Python exactly). So, for example, the following complex if tag:

   495 

   496     {% if a == b or c == d and e %}

   497 

   498 ...will be interpreted as:

   499 

   500 .. code-block:: python

   501 

   502     (a == b) or ((c == d) and e)

   503 

   504 If you need different precedence, you will need to use nested if tags. Sometimes

   505 that is better for clarity anyway, for the sake of those who do not know the

   506 precedence rules.

   507 

   508 

   509 .. templatetag:: ifchanged

   510 

   511 ifchanged

   512 ~~~~~~~~~

   513 

   514 Check if a value has changed from the last iteration of a loop.

   515 

   516 The 'ifchanged' block tag is used within a loop. It has two possible uses.

   517 

   518 1. Checks its own rendered contents against its previous state and only

   519    displays the content if it has changed. For example, this displays a list of

   520    days, only displaying the month if it changes::

   521 

   522         <h1>Archive for {{ year }}</h1>

   523 

   524         {% for date in days %}

   525             {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}

   526             <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>

   527         {% endfor %}

   528 

   529 2. If given a variable, check whether that variable has changed. For

   530    example, the following shows the date every time it changes, but

   531    only shows the hour if both the hour and the date has changed::

   532 

   533         {% for date in days %}

   534             {% ifchanged date.date %} {{ date.date }} {% endifchanged %}

   535             {% ifchanged date.hour date.date %}

   536                 {{ date.hour }}

   537             {% endifchanged %}

   538         {% endfor %}

   539 

   540 The ``ifchanged`` tag can also take an optional ``{% else %}`` clause that

   541 will be displayed if the value has not changed::

   542 

   543         {% for match in matches %}

   544             <div style="background-color:

   545                 {% ifchanged match.ballot_id %}

   546                     {% cycle "red" "blue" %}

   547                 {% else %}

   548                     grey

   549                 {% endifchanged %}

   550             ">{{ match }}</div>

   551         {% endfor %}

   552 

   553 .. templatetag:: ifequal

   554 

   555 ifequal

   556 ~~~~~~~

   557 

   558 Output the contents of the block if the two arguments equal each other.

   559 

   560 Example::

   561 

   562     {% ifequal user.id comment.user_id %}

   563         ...

   564     {% endifequal %}

   565 

   566 As in the ``{% if %}`` tag, an ``{% else %}`` clause is optional.

   567 

   568 The arguments can be hard-coded strings, so the following is valid::

   569 

   570     {% ifequal user.username "adrian" %}

   571         ...

   572     {% endifequal %}

   573 

   574 It is only possible to compare an argument to template variables or strings.

   575 You cannot check for equality with Python objects such as ``True`` or

   576 ``False``.  If you need to test if something is true or false, use the ``if``

   577 tag instead.

   578 

   579 .. versionadded:: 1.2

   580    An alternative to the ``ifequal`` tag is to use the :ttag:`if` tag and the ``==`` operator.

   581 

   582 .. templatetag:: ifnotequal

   583 

   584 ifnotequal

   585 ~~~~~~~~~~

   586 

   587 Just like ``ifequal``, except it tests that the two arguments are not equal.

   588 

   589 .. versionadded:: 1.2

   590    An alternative to the ``ifnotequal`` tag is to use the :ttag:`if` tag and the ``!=`` operator.

   591 

   592 .. templatetag:: include

   593 

   594 include

   595 ~~~~~~~

   596 

   597 Loads a template and renders it with the current context. This is a way of

   598 "including" other templates within a template.

   599 

   600 The template name can either be a variable or a hard-coded (quoted) string,

   601 in either single or double quotes.

   602 

   603 This example includes the contents of the template ``"foo/bar.html"``::

   604 

   605     {% include "foo/bar.html" %}

   606 

   607 This example includes the contents of the template whose name is contained in

   608 the variable ``template_name``::

   609 

   610     {% include template_name %}

   611 

   612 An included template is rendered with the context of the template that's

   613 including it. This example produces the output ``"Hello, John"``:

   614 

   615     * Context: variable ``person`` is set to ``"john"``.

   616     * Template::

   617 

   618         {% include "name_snippet.html" %}

   619 

   620     * The ``name_snippet.html`` template::

   621 

   622         Hello, {{ person }}

   623 

   624 See also: ``{% ssi %}``.

   625 

   626 .. note::

   627     The :ttag:`include` tag should be considered as an implementation of

   628     "render this subtemplate and include the HTML", not as "parse this

   629     subtemplate and include its contents as if it were part of the parent".

   630     This means that there is no shared state between included templates --

   631     each include is a completely independent rendering process.

   632 

   633 .. templatetag:: load

   634 

   635 load

   636 ~~~~

   637 

   638 Load a custom template tag set.

   639 

   640 See :doc:`Custom tag and filter libraries </howto/custom-template-tags>` for more information.

   641 

   642 .. templatetag:: now

   643 

   644 now

   645 ~~~

   646 

   647 Display the current date and/or time, according to the given string.

   648 

   649 Given format can be one of the predefined ones ``DATE_FORMAT``,

   650 ``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``,

   651 or a custom format, same as the :tfilter:`date` filter. Note that predefined

   652 formats may vary depending on the current locale.

   653 

   654 Example::

   655 

   656     It is {% now "jS F Y H:i" %}

   657 

   658 Note that you can backslash-escape a format string if you want to use the

   659 "raw" value. In this example, "f" is backslash-escaped, because otherwise

   660 "f" is a format string that displays the time. The "o" doesn't need to be

   661 escaped, because it's not a format character::

   662 

   663     It is the {% now "jS o\f F" %}

   664 

   665 This would display as "It is the 4th of September".

   666 

   667 .. templatetag:: regroup

   668 

   669 regroup

   670 ~~~~~~~

   671 

   672 Regroup a list of alike objects by a common attribute.

   673 

   674 This complex tag is best illustrated by use of an example: say that ``people``

   675 is a list of people represented by dictionaries with ``first_name``,

   676 ``last_name``, and ``gender`` keys:

   677 

   678 .. code-block:: python

   679 

   680     people = [

   681         {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},

   682         {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},

   683         {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},

   684         {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},

   685         {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},

   686     ]

   687 

   688 ...and you'd like to display a hierarchical list that is ordered by gender,

   689 like this:

   690 

   691     * Male:

   692         * George Bush

   693         * Bill Clinton

   694     * Female:

   695         * Margaret Thatcher

   696         * Condoleezza Rice

   697     * Unknown:

   698         * Pat Smith

   699 

   700 You can use the ``{% regroup %}`` tag to group the list of people by gender.

   701 The following snippet of template code would accomplish this::

   702 

   703     {% regroup people by gender as gender_list %}

   704 

   705     <ul>

   706     {% for gender in gender_list %}

   707         <li>{{ gender.grouper }}

   708         <ul>

   709             {% for item in gender.list %}

   710             <li>{{ item.first_name }} {{ item.last_name }}</li>

   711             {% endfor %}

   712         </ul>

   713         </li>

   714     {% endfor %}

   715     </ul>

   716 

   717 Let's walk through this example. ``{% regroup %}`` takes three arguments: the

   718 list you want to regroup, the attribute to group by, and the name of the

   719 resulting list. Here, we're regrouping the ``people`` list by the ``gender``

   720 attribute and calling the result ``gender_list``.

   721 

   722 ``{% regroup %}`` produces a list (in this case, ``gender_list``) of

   723 **group objects**. Each group object has two attributes:

   724 

   725     * ``grouper`` -- the item that was grouped by (e.g., the string "Male" or

   726       "Female").

   727     * ``list`` -- a list of all items in this group (e.g., a list of all people

   728       with gender='Male').

   729 

   730 Note that ``{% regroup %}`` does not order its input! Our example relies on

   731 the fact that the ``people`` list was ordered by ``gender`` in the first place.

   732 If the ``people`` list did *not* order its members by ``gender``, the regrouping

   733 would naively display more than one group for a single gender. For example,

   734 say the ``people`` list was set to this (note that the males are not grouped

   735 together):

   736 

   737 .. code-block:: python

   738 

   739     people = [

   740         {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},

   741         {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},

   742         {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},

   743         {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},

   744         {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},

   745     ]

   746 

   747 With this input for ``people``, the example ``{% regroup %}`` template code

   748 above would result in the following output:

   749 

   750     * Male:

   751         * Bill Clinton

   752     * Unknown:

   753         * Pat Smith

   754     * Female:

   755         * Margaret Thatcher

   756     * Male:

   757         * George Bush

   758     * Female:

   759         * Condoleezza Rice

   760 

   761 The easiest solution to this gotcha is to make sure in your view code that the

   762 data is ordered according to how you want to display it.

   763 

   764 Another solution is to sort the data in the template using the ``dictsort``

   765 filter, if your data is in a list of dictionaries::

   766 

   767     {% regroup people|dictsort:"gender" by gender as gender_list %}

   768 

   769 .. templatetag:: spaceless

   770 

   771 spaceless

   772 ~~~~~~~~~

   773 

   774 Removes whitespace between HTML tags. This includes tab

   775 characters and newlines.

   776 

   777 Example usage::

   778 

   779     {% spaceless %}

   780         <p>

   781             <a href="foo/">Foo</a>

   782         </p>

   783     {% endspaceless %}

   784 

   785 This example would return this HTML::

   786 

   787     <p><a href="foo/">Foo</a></p>

   788 

   789 Only space between *tags* is removed -- not space between tags and text. In

   790 this example, the space around ``Hello`` won't be stripped::

   791 

   792     {% spaceless %}

   793         <strong>

   794             Hello

   795         </strong>

   796     {% endspaceless %}

   797 

   798 .. templatetag:: ssi

   799 

   800 ssi

   801 ~~~

   802 

   803 Output the contents of a given file into the page.

   804 

   805 Like a simple "include" tag, ``{% ssi %}`` includes the contents of another

   806 file -- which must be specified using an absolute path -- in the current

   807 page::

   808 

   809     {% ssi /home/html/ljworld.com/includes/right_generic.html %}

   810 

   811 If the optional "parsed" parameter is given, the contents of the included

   812 file are evaluated as template code, within the current context::

   813 

   814     {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}

   815 

   816 Note that if you use ``{% ssi %}``, you'll need to define

   817 :setting:`ALLOWED_INCLUDE_ROOTS` in your Django settings, as a security measure.

   818 

   819 See also: ``{% include %}``.

   820 

   821 .. templatetag:: templatetag

   822 

   823 templatetag

   824 ~~~~~~~~~~~

   825 

   826 Output one of the syntax characters used to compose template tags.

   827 

   828 Since the template system has no concept of "escaping", to display one of the

   829 bits used in template tags, you must use the ``{% templatetag %}`` tag.

   830 

   831 The argument tells which template bit to output:

   832 

   833     ==================  =======

   834     Argument            Outputs

   835     ==================  =======

   836     ``openblock``       ``{%``

   837     ``closeblock``      ``%}``

   838     ``openvariable``    ``{{``

   839     ``closevariable``   ``}}``

   840     ``openbrace``       ``{``

   841     ``closebrace``      ``}``

   842     ``opencomment``     ``{#``

   843     ``closecomment``    ``#}``

   844     ==================  =======

   845 

   846 .. templatetag:: url

   847 

   848 url

   849 ~~~

   850 

   851 Returns an absolute path reference (a URL without the domain name) matching a

   852 given view function and optional parameters. This is a way to output links

   853 without violating the DRY principle by having to hard-code URLs in your

   854 templates::

   855 

   856     {% url path.to.some_view v1 v2 %}

   857 

   858 The first argument is a path to a view function in the format

   859 ``package.package.module.function``. Additional arguments are optional and

   860 should be space-separated values that will be used as arguments in the URL.

   861 The example above shows passing positional arguments. Alternatively you may

   862 use keyword syntax::

   863 

   864     {% url path.to.some_view arg1=v1 arg2=v2 %}

   865 

   866 Do not mix both positional and keyword syntax in a single call. All arguments

   867 required by the URLconf should be present.

   868 

   869 For example, suppose you have a view, ``app_views.client``, whose URLconf

   870 takes a client ID (here, ``client()`` is a method inside the views file

   871 ``app_views.py``). The URLconf line might look like this:

   872 

   873 .. code-block:: python

   874 

   875     ('^client/(\d+)/$', 'app_views.client')

   876 

   877 If this app's URLconf is included into the project's URLconf under a path

   878 such as this:

   879 

   880 .. code-block:: python

   881 

   882     ('^clients/', include('project_name.app_name.urls'))

   883 

   884 ...then, in a template, you can create a link to this view like this::

   885 

   886     {% url app_views.client client.id %}

   887 

   888 The template tag will output the string ``/clients/client/123/``.

   889 

   890 .. versionadded:: 1.0

   891 

   892 If you're using :ref:`named URL patterns <naming-url-patterns>`, you can

   893 refer to the name of the pattern in the ``url`` tag instead of using the

   894 path to the view.

   895 

   896 Note that if the URL you're reversing doesn't exist, you'll get an

   897 :exc:`NoReverseMatch` exception raised, which will cause your site to display an

   898 error page.

   899 

   900 .. versionadded:: 1.0

   901 

   902 If you'd like to retrieve a URL without displaying it, you can use a slightly

   903 different call::

   904 

   905 

   906     {% url path.to.view arg arg2 as the_url %}

   907 

   908     <a href="{{ the_url }}">I'm linking to {{ the_url }}</a>

   909 

   910 This ``{% url ... as var %}`` syntax will *not* cause an error if the view is

   911 missing. In practice you'll use this to link to views that are optional::

   912 

   913     {% url path.to.view as the_url %}

   914     {% if the_url %}

   915       <a href="{{ the_url }}">Link to optional stuff</a>

   916     {% endif %}

   917 

   918 .. versionadded:: 1.1

   919 

   920 If you'd like to retrieve a namespaced URL, specify the fully qualified name::

   921 

   922     {% url myapp:view-name %}

   923 

   924 This will follow the normal :ref:`namespaced URL resolution strategy

   925 <topics-http-reversing-url-namespaces>`, including using any hints provided

   926 by the context as to the current application.

   927 

   928 .. versionchanged:: 1.2

   929 

   930 For backwards compatibility, the ``{% url %}`` tag also supports the

   931 use of commas to separate arguments. You shouldn't use this in any new

   932 projects, but for the sake of the people who are still using it,

   933 here's what it looks like::

   934 

   935     {% url path.to.view arg,arg2 %}

   936     {% url path.to.view arg, arg2 %}

   937 

   938 This syntax doesn't support the use of literal commas, or or equals

   939 signs. Did we mention you shouldn't use this syntax in any new

   940 projects?

   941 

   942 .. templatetag:: widthratio

   943 

   944 widthratio

   945 ~~~~~~~~~~

   946 

   947 For creating bar charts and such, this tag calculates the ratio of a given value

   948 to a maximum value, and then applies that ratio to a constant.

   949 

   950 For example::

   951 

   952     <img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" />

   953 

   954 Above, if ``this_value`` is 175 and ``max_value`` is 200, the image in the

   955 above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5

   956 which is rounded up to 88).

   957 

   958 .. templatetag:: with

   959 

   960 with

   961 ~~~~

   962 

   963 .. versionadded:: 1.0

   964 

   965 Caches a complex variable under a simpler name. This is useful when accessing

   966 an "expensive" method (e.g., one that hits the database) multiple times.

   967 

   968 For example::

   969 

   970     {% with business.employees.count as total %}

   971         {{ total }} employee{{ total|pluralize }}

   972     {% endwith %}

   973 

   974 The populated variable (in the example above, ``total``) is only available

   975 between the ``{% with %}`` and ``{% endwith %}`` tags.

   976 

   977 .. _ref-templates-builtins-filters:

   978 

   979 Built-in filter reference

   980 -------------------------

   981 

   982 .. templatefilter:: add

   983 

   984 add

   985 ~~~

   986 

   987 Adds the argument to the value.

   988 

   989 For example::

   990 

   991     {{ value|add:"2" }}

   992 

   993 If ``value`` is ``4``, then the output will be ``6``.

   994 

   995 .. versionchanged:: 1.2

   996    The following behavior didn't exist in previous Django versions.

   997 

   998 This filter will first try to coerce both values to integers. If this fails,

   999 it'll attempt to add the values together anyway. This will work on some data

  1000 types (strings, list, etc.) and fail on others. If it fails, the result will

  1001 be an empty string.

  1002 

  1003 For example, if we have::

  1004 

  1005     {{ first|add:second }}

  1006 

  1007 and ``first`` is ``[1, 2, 3]`` and ``second`` is ``[4, 5, 6]``, then the

  1008 output will be ``[1, 2, 3, 4, 5, 6]``.

  1009 

  1010 .. warning::

  1011 

  1012     Strings that can be coerced to integers will be **summed**, not

  1013     concatenated, as in the first example above.

  1014 

  1015 .. templatefilter:: addslashes

  1016 

  1017 addslashes

  1018 ~~~~~~~~~~

  1019 

  1020 Adds slashes before quotes. Useful for escaping strings in CSV, for example.

  1021 

  1022 For example::

  1023 

  1024     {{ value|addslashes }}

  1025 

  1026 If ``value`` is ``"I'm using Django"``, the output will be ``"I\'m using Django"``.

  1027 

  1028 .. templatefilter:: capfirst

  1029 

  1030 capfirst

  1031 ~~~~~~~~

  1032 

  1033 Capitalizes the first character of the value.

  1034 

  1035 For example::

  1036 

  1037     {{ value|capfirst }}

  1038 

  1039 If ``value`` is ``"django"``, the output will be ``"Django"``.

  1040 

  1041 .. templatefilter:: center

  1042 

  1043 center

  1044 ~~~~~~

  1045 

  1046 Centers the value in a field of a given width.

  1047 

  1048 For example::

  1049 

  1050     "{{ value|center:"15" }}"

  1051 

  1052 If ``value`` is ``"Django"``, the output will be ``"     Django    "``.

  1053 

  1054 .. templatefilter:: cut

  1055 

  1056 cut

  1057 ~~~

  1058 

  1059 Removes all values of arg from the given string.

  1060 

  1061 For example::

  1062 

  1063     {{ value|cut:" "}}

  1064 

  1065 If ``value`` is ``"String with spaces"``, the output will be ``"Stringwithspaces"``.

  1066 

  1067 .. templatefilter:: date

  1068 

  1069 date

  1070 ~~~~

  1071 

  1072 Formats a date according to the given format.

  1073 

  1074 Uses the same format as PHP's ``date()`` function (http://php.net/date)

  1075 with some custom extensions.

  1076 

  1077 Available format strings:

  1078 

  1079     ================  ========================================  =====================

  1080     Format character  Description                               Example output

  1081     ================  ========================================  =====================

  1082     a                 ``'a.m.'`` or ``'p.m.'`` (Note that       ``'a.m.'``

  1083                       this is slightly different than PHP's

  1084                       output, because this includes periods

  1085                       to match Associated Press style.)

  1086     A                 ``'AM'`` or ``'PM'``.                     ``'AM'``

  1087     b                 Month, textual, 3 letters, lowercase.     ``'jan'``

  1088     B                 Not implemented.

  1089     c                 ISO 8601 Format.                          ``2008-01-02T10:30:00.000123``

  1090     d                 Day of the month, 2 digits with           ``'01'`` to ``'31'``

  1091                       leading zeros.

  1092     D                 Day of the week, textual, 3 letters.      ``'Fri'``

  1093     f                 Time, in 12-hour hours and minutes,       ``'1'``, ``'1:30'``

  1094                       with minutes left off if they're zero.

  1095                       Proprietary extension.

  1096     F                 Month, textual, long.                     ``'January'``

  1097     g                 Hour, 12-hour format without leading      ``'1'`` to ``'12'``

  1098                       zeros.

  1099     G                 Hour, 24-hour format without leading      ``'0'`` to ``'23'``

  1100                       zeros.

  1101     h                 Hour, 12-hour format.                     ``'01'`` to ``'12'``

  1102     H                 Hour, 24-hour format.                     ``'00'`` to ``'23'``

  1103     i                 Minutes.                                  ``'00'`` to ``'59'``

  1104     I                 Not implemented.

  1105     j                 Day of the month without leading          ``'1'`` to ``'31'``

  1106                       zeros.

  1107     l                 Day of the week, textual, long.           ``'Friday'``

  1108     L                 Boolean for whether it's a leap year.     ``True`` or ``False``

  1109     m                 Month, 2 digits with leading zeros.       ``'01'`` to ``'12'``

  1110     M                 Month, textual, 3 letters.                ``'Jan'``

  1111     n                 Month without leading zeros.              ``'1'`` to ``'12'``

  1112     N                 Month abbreviation in Associated Press    ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'``

  1113                       style. Proprietary extension.

  1114     O                 Difference to Greenwich time in hours.    ``'+0200'``

  1115     P                 Time, in 12-hour hours, minutes and       ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'``

  1116                       'a.m.'/'p.m.', with minutes left off

  1117                       if they're zero and the special-case

  1118                       strings 'midnight' and 'noon' if

  1119                       appropriate. Proprietary extension.

  1120     r                 RFC 2822 formatted date.                  ``'Thu, 21 Dec 2000 16:01:07 +0200'``

  1121     s                 Seconds, 2 digits with leading zeros.     ``'00'`` to ``'59'``

  1122     S                 English ordinal suffix for day of the     ``'st'``, ``'nd'``, ``'rd'`` or ``'th'``

  1123                       month, 2 characters.

  1124     t                 Number of days in the given month.        ``28`` to ``31``

  1125     T                 Time zone of this machine.                ``'EST'``, ``'MDT'``

  1126     u                 Microseconds.                             ``0`` to ``999999``

  1127     U                 Seconds since the Unix Epoch

  1128                       (January 1 1970 00:00:00 UTC).

  1129     w                 Day of the week, digits without           ``'0'`` (Sunday) to ``'6'`` (Saturday)

  1130                       leading zeros.

  1131     W                 ISO-8601 week number of year, with        ``1``, ``53``

  1132                       weeks starting on Monday.

  1133     y                 Year, 2 digits.                           ``'99'``

  1134     Y                 Year, 4 digits.                           ``'1999'``

  1135     z                 Day of the year.                          ``0`` to ``365``

  1136     Z                 Time zone offset in seconds. The          ``-43200`` to ``43200``