Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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: http://code.djangoproject.com/svn/django/trunk@13063 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit b26aa18c5c97f4883c56bd0a17e0b9257e5acd46 1 parent d2b5a6c
Russell Keith-Magee authored May 01, 2010
7  docs/ref/templates/builtins.txt
@@ -619,6 +619,13 @@ including it. This example produces the output ``"Hello, John"``:
619 619
 
620 620
 See also: ``{% ssi %}``.
621 621
 
  622
+.. note::
  623
+    The :ttag:`include` tag should be considered as an implementation of
  624
+    "render this subtemplate and include the HTML", not as "parse this
  625
+    subtemplate and include its contents as if it were part of the parent".
  626
+    This means that there is no shared state between included templates --
  627
+    each include is a completely independent rendering process.
  628
+
622 629
 .. templatetag:: load
623 630
 
624 631
 load
28  docs/releases/1.2.txt
@@ -230,6 +230,34 @@ party packages, or from your own code, you should ensure that the
230 230
 information, see
231 231
 :ref:`template tag thread safety considerations<template_tag_thread_safety>`.
232 232
 
  233
+You may also need to update your templates if you were relying on the
  234
+implementation of Django's template tags *not* being thread safe. The
  235
+:ttag:`cycle` tag is the most likely to be affected in this way,
  236
+especially when used in conjunction with the :ttag:`include` tag.
  237
+Consider the following template fragment::
  238
+
  239
+    {% for object in object_list %}
  240
+        {% include "subtemplate.html" %}
  241
+    {% endfor %}
  242
+
  243
+with a ``subtemplate.html`` that reads::
  244
+
  245
+    {% cycle 'even' 'odd' %}
  246
+
  247
+Using the non thread-safe, pre-Django 1.2 renderer, this would output::
  248
+
  249
+    even odd even odd ...
  250
+
  251
+Using the thread-safe Django 1.2 renderer, you will instead get::
  252
+
  253
+    even even even even ...
  254
+
  255
+This is because the each rendering of the :ttag:`include` tag is an
  256
+independent rendering. When the :ttag:`cycle` tag was not thread safe,
  257
+the state of the :ttag:`cycle` tag would leak between multiple renderings
  258
+of the same :ttag:`include`. Now that the :ttag:`cycle` tag is thread safe,
  259
+this leakage no longer occurs.
  260
+
233 261
 Test runner exit status code
234 262
 ----------------------------
235 263
 

0 notes on commit b26aa18

Please sign in to comment.
Something went wrong with that request. Please try again.