From 1ccdc08189fd509ba87a4d916173baff7b2642a5 Mon Sep 17 00:00:00 2001 From: "Paul C. Anagnostopoulos" Date: Wed, 21 Aug 2013 13:53:38 -0400 Subject: [PATCH] Clarified docs for some tags and filters --- docs/ref/templates/builtins.txt | 177 +++++++++++++++++--------------- 1 file changed, 95 insertions(+), 82 deletions(-) diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 767906cd8b..9d096e44b3 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -60,6 +60,8 @@ Sample usage::

Commented out text with {{ create_date|date:"c" }}

{% endcomment %} +``comment`` tags cannot be nested. + .. templatetag:: csrf_token csrf_token @@ -73,10 +75,12 @@ This tag is used for CSRF protection, as described in the documentation for 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 %} @@ -84,8 +88,13 @@ loop:: {% 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 %} @@ -93,9 +102,10 @@ You can use variables, too. For example, if you have two template variables, {% 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 %} @@ -111,17 +121,17 @@ You can mix variables and strings:: {% 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:: ... @@ -143,15 +153,39 @@ would output:: ... -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. +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. -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. +By default, when you use the ``as`` keyword with the cycle tag, the +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 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 backwards compatibility, the ``{% cycle %}`` tag supports the much inferior + {% for obj in some_list %} + {% cycle 'row1' 'row2' as rowcolors silent %} + {% include "subtemplate.html" %} + {% endfor %} + +This will output a list of ```` elements with ``class`` +alternating between ``row1`` and ``row2``. The subtemplate will have +access to ``rowcolors`` in its context and the value will match the class +of the ```` that encloses it. If the ``silent`` keyword were to be +omitted, ``row1`` and ``row2`` would be emitted as normal text, outside the +```` element. + +When the silent keyword is used on a cycle definition, the silence +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:: @@ -162,48 +196,21 @@ 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? -By default, when you use the ``as`` keyword with the cycle tag, the -usage of ``{% cycle %}`` that declares the cycle will itself output -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 -``silent`` keyword as the last keyword in the tag. For example:: - - {% for obj in some_list %} - {% cycle 'row1' 'row2' as rowcolors silent %} - {% include "subtemplate.html" %} - {% endfor %} - -This will output a list of ```` elements with ``class`` -alternating between ``row1`` and ``row2``; the subtemplate will have -access to ``rowcolors`` in its context that matches the class of the -```` that encloses it. If the ``silent`` keyword were to be -omitted, ``row1`` would be emitted as normal text, outside the -```` 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:: - - {% cycle 'row1' 'row2' as rowcolors silent %} - {% cycle rowcolors %} - .. versionchanged:: 1.6 - To improve safety, future versions of ``cycle`` will automatically escape - their output. You're encouraged to activate this behavior by loading - ``cycle`` from the ``future`` template library:: +To improve safety, future versions of ``cycle`` will automatically escape +their output. You're encouraged to activate this behavior by loading +``cycle`` from the ``future`` template library:: - {% load cycle from future %} + {% load cycle from future %} - When using the ``future`` version, you can disable auto-escaping with:: +When using the ``future`` version, you can disable auto-escaping with:: - {% for o in some_list %} - - ... - - {% endfor %} + {% for o in some_list %} + + ... + + {% endfor %} .. templatetag:: debug @@ -237,10 +244,12 @@ See :ref:`template-inheritance` for more information. 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:: @@ -259,8 +268,8 @@ 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. @@ -315,8 +324,9 @@ to escape the variables in the firstof tag, you must do so explicitly:: 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``::