Browse files

Fixed #13444 -- Improved the documentation around the backwards compa…

…tibility quirks of the cycle and include tags. Thanks to awmcclain for the report.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
freakboy3742 committed May 1, 2010
1 parent d2b5a6c commit b26aa18c5c97f4883c56bd0a17e0b9257e5acd46
Showing with 35 additions and 0 deletions.
  1. +7 −0 docs/ref/templates/builtins.txt
  2. +28 −0 docs/releases/1.2.txt
@@ -619,6 +619,13 @@ including it. This example produces the output ``"Hello, John"``:
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
@@ -230,6 +230,34 @@ party packages, or from your own code, you should ensure that the
information, see
:ref:`template tag thread safety considerations<template_tag_thread_safety>`.
+You may also need to update your templates if you were relying on the
+implementation of Django's template tags *not* being thread safe. The
+:ttag:`cycle` tag is the most likely to be affected in this way,
+especially when used in conjunction with the :ttag:`include` tag.
+Consider the following template fragment::
+ {% for object in object_list %}
+ {% include "subtemplate.html" %}
+ {% endfor %}
+with a ``subtemplate.html`` that reads::
+ {% cycle 'even' 'odd' %}
+Using the non thread-safe, pre-Django 1.2 renderer, this would output::
+ even odd even odd ...
+Using the thread-safe Django 1.2 renderer, you will instead get::
+ even even even even ...
+This is because the each rendering of the :ttag:`include` tag is an
+independent rendering. When the :ttag:`cycle` tag was not thread safe,
+the state of the :ttag:`cycle` tag would leak between multiple renderings
+of the same :ttag:`include`. Now that the :ttag:`cycle` tag is thread safe,
+this leakage no longer occurs.
Test runner exit status code

0 comments on commit b26aa18

Please sign in to comment.