From fe0eb2f995434adbfeae9617b8231e0b3bbd3fa4 Mon Sep 17 00:00:00 2001 From: "Paul C. Anagnostopoulos" Date: Wed, 21 Aug 2013 13:53:38 -0400 Subject: [1.6.x] Clarified docs for some tags and filters Backport of 1ccdc08189 from master --- docs/ref/templates/builtins.txt | 165 ++++++++++++++++++++++------------------ 1 file changed, 89 insertions(+), 76 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index afb6e4b123..929c66a8cc 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,30 +153,16 @@ 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. - -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 %} @@ -175,35 +171,46 @@ just declare the cycle, but not output the first value, you can add a {% 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 +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 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 - 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``::