Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
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: http://code.djangoproject.com/svn/django/trunk@13063 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit b26aa18c5c97f4883c56bd0a17e0b9257e5acd46 1 parent d2b5a6c
@freakboy3742 freakboy3742 authored
Showing with 35 additions and 0 deletions.
  1. +7 −0 docs/ref/templates/builtins.txt
  2. +28 −0 docs/releases/1.2.txt
View
7 docs/ref/templates/builtins.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
load
View
28 docs/releases/1.2.txt
@@ -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.
Something went wrong with that request. Please try again.