mirror of
https://github.com/django/django.git
synced 2025-01-27 18:49:23 +00:00
[4.2.x] Fixed #34574 -- Noted unexpected outcomes in autoescape/escape docs.
Backport of 1a59a324cec5caf12ea0c4947564828aa7bda02a from main.
This commit is contained in:
parent
91f8df5c2e
commit
25bd9faf32
@ -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
|
``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.
|
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:
|
Sample usage:
|
||||||
|
|
||||||
.. code-block:: html+django
|
.. code-block:: html+django
|
||||||
@ -38,6 +29,33 @@ Sample usage:
|
|||||||
{{ body }}
|
{{ body }}
|
||||||
{% endautoescape %}
|
{% 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
|
.. templatetag:: block
|
||||||
|
|
||||||
``block``
|
``block``
|
||||||
@ -1832,6 +1850,16 @@ For example, you can apply ``escape`` to fields when :ttag:`autoescape` is off:
|
|||||||
{{ title|escape }}
|
{{ title|escape }}
|
||||||
{% endautoescape %}
|
{% 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
|
.. templatefilter:: escapejs
|
||||||
|
|
||||||
``escapejs``
|
``escapejs``
|
||||||
|
@ -415,6 +415,7 @@ redisplayed
|
|||||||
redisplaying
|
redisplaying
|
||||||
redisplays
|
redisplays
|
||||||
reenable
|
reenable
|
||||||
|
reescape
|
||||||
referer
|
referer
|
||||||
referers
|
referers
|
||||||
reflow
|
reflow
|
||||||
|
Loading…
x
Reference in New Issue
Block a user