1
0
mirror of https://github.com/django/django.git synced 2024-12-25 10:35:48 +00:00

[4.2.x] Fixed #34574 -- Noted unexpected outcomes in autoescape/escape docs.

Backport of 1a59a324ce from main.
This commit is contained in:
Natalia 2023-05-24 13:59:00 -03:00 committed by Mariusz Felisiak
parent 91f8df5c2e
commit 25bd9faf32
2 changed files with 38 additions and 9 deletions

View File

@ -21,15 +21,6 @@ Controls the current auto-escaping behavior. This tag takes either ``on`` or
``off`` as an argument and that determines whether auto-escaping is in effect
inside the block. The block is closed with an ``endautoescape`` ending tag.
When auto-escaping is in effect, all variable content has HTML escaping applied
to it before placing the result into the output (but after any filters have
been applied). This is equivalent to manually applying the :tfilter:`escape`
filter to each variable.
The only exceptions are variables that are already marked as "safe" from
escaping, either by the code that populated the variable, or because it has had
the :tfilter:`safe` or :tfilter:`escape` filters applied.
Sample usage:
.. code-block:: html+django
@ -38,6 +29,33 @@ Sample usage:
{{ body }}
{% endautoescape %}
When auto-escaping is in effect, all content derived from variables has HTML
escaping applied before placing the result into the output (but after any
filters are applied). This is equivalent to manually applying the
:tfilter:`escape` filter to each variable.
The only exceptions are variables already marked as "safe" from escaping.
Variables could be marked as "safe" by the code which populated the variable,
by applying the :tfilter:`safe` or :tfilter:`escape` filters, or because it's
the result of a previous filter that marked the string as "safe".
Within the scope of disabled auto-escaping, chaining filters, including
:tfilter:`escape`, may cause unexpected (but documented) results such as the
following:
.. code-block:: html+django
{% autoescape off %}
{{ my_list|join:", "|escape }}
{% endautoescape %}
The above code will output the joined elements of ``my_list`` unescaped. This
is because the filter chaining sequence executes first :tfilter:`join` on
``my_list`` (without applying escaping to each item since ``autoescape`` is
``off``), marking the result as safe. Subsequently, this safe result will be
fed to :tfilter:`escape` filter, which does not apply a second round of
escaping.
.. templatetag:: block
``block``
@ -1832,6 +1850,16 @@ For example, you can apply ``escape`` to fields when :ttag:`autoescape` is off:
{{ title|escape }}
{% endautoescape %}
.. admonition:: Chaining ``escape`` with other filters
As mentioned in the :ttag:`autoescape` section, when filters including
``escape`` are chained together, it can result in unexpected outcomes if
preceding filters mark a potentially unsafe string as safe due to the lack
of escaping caused by :ttag:`autoescape` being ``off``.
In such cases, chaining ``escape`` would not reescape strings that have
already been marked as safe.
.. templatefilter:: escapejs
``escapejs``

View File

@ -415,6 +415,7 @@ redisplayed
redisplaying
redisplays
reenable
reescape
referer
referers
reflow