Clarified docs for some tags and filters

        <p>Commented out text with {{ create_date|date:"c" }}</p>

    {% endcomment %}

``comment`` tags cannot be nested.

.. templatetag:: csrf_token

csrf_token

cycle

^^^^^

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

Produces one of its arguments each time this tag is encountered. The first

argument is produced on the first encounter, the second argument on the second

encounter, and so forth. Once all arguments are exhausted, the tag cycles to

the first argument and produces it again.

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

loop::

This tag is particularly useful in a loop::

    {% for o in some_list %}

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

        </tr>

    {% endfor %}

The first iteration produces HTML that refers to class ``row1``, the second to

``row2``, the third to ``row1`` again, and so on for each iteration of the

loop.

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

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

``rowvalue1`` and ``rowvalue2``, you can alternate between their values like

this::

    {% for o in some_list %}

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

        </tr>

    {% endfor %}

Note that variable arguments (``rowvalue1`` and ``rowvalue2`` above) are NOT

auto-escaped! So either make sure that you trust their values, or use explicit

escaping, like this::

Note that the variables included in the cycle will not be escaped. Any HTML or

Javascript code contained in the printed variable will be rendered as-is, which

could potentially lead to security issues. So either make sure that you trust

their values or use explicit escaping like this::

    {% for o in some_list %}

        <tr class="{% filter force_escape %}{% cycle rowvalue1 rowvalue2 %}{% endfilter %}">

        </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::

In some cases you might want to refer to the current value of a cycle

without advancing to the next value. 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 by referencing the cycle name as a context

variable. If you want to move the cycle onto the next value, you use

the cycle tag again, using the name of the variable. So, the following

template::

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

in your template by referencing the cycle name as a context variable. If you

want to move the cycle to the next value independently of the original

``cycle`` tag, you can use another ``cycle`` tag and specify the name of the

variable. So, the following template::

    <tr>

        <td class="{% cycle 'row1' 'row2' as rowcolors %}">...</td>

        <td class="row2">...</td>

    </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 currently the variables included in the cycle will not be escaped.

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

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

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?

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

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

as string literals, while values without quotes are treated as template

variables.

By default, when you use the ``as`` keyword with the cycle tag, the

usage of ``{% cycle %}`` that declares the cycle will itself output

usage of ``{% cycle %}`` that initiates the cycle will itself produce

the first value in the cycle. This could be a problem if you want to

use the value in a nested loop or an included template. If you want to

just declare the cycle, but not output the first value, you can add a

use the value in a nested loop or an included template. If you only want

to declare the cycle but not produce the first value, you can add a

``silent`` keyword as the last keyword in the tag. For example::

    {% for obj in some_list %}

    {% endfor %}

This will output a list of ``<tr>`` elements with ``class``

alternating between ``row1`` and ``row2``; the subtemplate will have

access to ``rowcolors`` in its context that matches the class of the

``<tr>`` that encloses it. If the ``silent`` keyword were to be

omitted, ``row1`` would be emitted as normal text, outside the

alternating between ``row1`` and ``row2``. The subtemplate will have

access to ``rowcolors`` in its context and the value will match the class

of the ``<tr>`` that encloses it. If the ``silent`` keyword were to be

omitted, ``row1`` and ``row2`` would be emitted as normal text, outside the

``<tr>`` element.

When the silent keyword is used on a cycle definition, the silence

automatically applies to all subsequent uses of the cycle tag. In,

the following template would output *nothing*, even though the second

call to ``{% cycle %}`` doesn't specify silent::

automatically applies to all subsequent uses of that specific cycle tag.

The following template would output *nothing*, even though the second

call to ``{% cycle %}`` doesn't specify ``silent``::

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

    {% cycle rowcolors %}

For backward 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?

.. versionchanged:: 1.6

To improve safety, future versions of ``cycle`` will automatically escape

filter

^^^^^^

Filters the contents of the variable through variable filters.

Filters the contents of the block through one or more filters. Multiple

filters can be specified with pipes and filters can have arguments, just as

in variable syntax.

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

just like in variable syntax.

Note that the block includes *all* the text between the ``filter`` and

``endfilter`` tags.

Sample usage::

firstof

^^^^^^^

Outputs the first variable passed that is not False. Does NOT auto-escape

variable values.

Outputs the first argument variable that is not False. This tag does *not*

auto-escape variable values.

Outputs nothing if all the passed variables are False.

for

^^^

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

provided in ``athlete_list``::

Loops over each item in an array, making the item available in a context

variable. For example, to display a list of athletes provided in

``athlete_list``::

    <ul>

    {% for athlete in athlete_list %}

``{% for obj in list reversed %}``.

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

in each sublist 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::

                            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

``forloop.parentloop``      For nested loops, this is the loop surrounding

                            the current one

==========================  ===============================================

for ... empty

^^^^^^^^^^^^^

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

The ``for`` tag can take an optional ``{% empty %}`` clause whose text is

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

    <ul>

    accepts a context. This allows you to reference a compiled ``Template`` in

    your context.

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

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

An included template is rendered within the context of the template that

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

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

* Template::

    {% include "name_snippet.html" with person="Jane" greeting="Hello" %}

If you want to only render the context with the variables provided (or even

no variables at all), use the ``only`` option::

If you want to render the context only with the variables provided (or even

no variables at all), use the ``only`` option. No other variables are

available to the included template::

    {% include "name_snippet.html" with greeting="Hi" only %}

capfirst

^^^^^^^^

Capitalizes the first character of the value.

Capitalizes the first character of the value. If the first character is not

a letter, this filter has no effect.

For example::

title

^^^^^

Converts a string into titlecase.

Converts a string into titlecase by capitalizing each word in the string.

This tag makes no effort to keep "trivial words" in lowercase.

For example::