From 7df57fd591757ac561297ca32ff695a37061cdcc Mon Sep 17 00:00:00 2001
From: Hugo Alliaume <hugo@alliau.me>
Date: Thu, 19 Sep 2024 11:57:45 +0200
Subject: [PATCH] =?UTF-8?q?[Doc]=C2=A0Document=20about=20`html`=20and=20`h?=
 =?UTF-8?q?tml=5Fattr`=20strategies?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 doc/filters/escape.rst | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/doc/filters/escape.rst b/doc/filters/escape.rst
index 574724e35bd..89d903f6296 100644
--- a/doc/filters/escape.rst
+++ b/doc/filters/escape.rst
@@ -39,7 +39,7 @@ 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 +50,7 @@ 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 +90,24 @@ 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
+
+        <p {{ your_html_attr|e('html_attr') }}="attribute value">
+    
+    It can also be used for escaping **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 ``html`` escaping strategy.
+
+    .. code-block:: html+twig
+        <p data-content="{{ content|e('html') }}">
+        {# is equivalent to, but is less performant #}
+        <p data-content={{ content|e('html_attr') }}>
+
 Custom Escapers
 ---------------