diff --git a/doc/filters/escape.rst b/doc/filters/escape.rst index 574724e35b..875509862d 100644 --- a/doc/filters/escape.rst +++ b/doc/filters/escape.rst @@ -39,7 +39,8 @@ And here is how to escape variables included in JavaScript code: The ``escape`` filter supports the following escaping strategies for HTML documents: -* ``html``: escapes a string for the **HTML body** context. +* ``html``: escapes a string for the **HTML body** context, + or for HTML attributes values **inside quotes**. * ``js``: escapes a string for the **JavaScript** context. @@ -50,7 +51,8 @@ documents: * ``url``: escapes a string for the **URI or parameter** contexts. This should not be used to escape an entire URI; only a subcomponent being inserted. -* ``html_attr``: escapes a string for the **HTML attribute** context. +* ``html_attr``: escapes a string for the **HTML attribute** context, + **without quotes** around HTML attribute values. Note that doing contextual escaping in HTML documents is hard and choosing the right escaping strategy depends on a lot of factors. Please, read related @@ -90,6 +92,27 @@ to learn more about this topic. {{ var|escape(strategy)|raw }} {# won't be double-escaped #} {% endautoescape %} +.. tip:: + + The ``html_attr`` escaping strategy can be useful when you need to + escape a **dynamic HTML attribute name**: + + .. code-block:: html+twig + +

+ + It can also be used for escaping a **dynamic HTML attribute value** + if it is not quoted, but this is **less performant**. + Instead, it is recommended to quote the HTML attribute value + and use the ``html`` escaping strategy: + + .. code-block:: html+twig + +

+ + {# is equivalent to, but is less performant #} +

+ Custom Escapers ---------------