Fixed #13444 -- Improved the documentation around the backwards compatibility 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
This commit is contained in:
Russell Keith-Magee 2010-05-01 14:27:10 +00:00
parent d2b5a6c8d7
commit b26aa18c5c
2 changed files with 35 additions and 0 deletions

View File

@ -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 File

@ -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
----------------------------