Browse code

added a note about double-escaping when using a variable for the strategy (closes #868)

Fabien Potencier authored on 30/10/2012 09:25:30
Showing 2 changed files
... ...
@@ -496,10 +496,10 @@ The escaping rules are implemented as follows:
496 496
 
497 497
   .. code-block:: jinja
498 498
 
499
-        {% autoescape true js %}
500
-        {{ var|escape('html') }} {# will be escaped for html and javascript #}
501
-        {{ var }} {# will be escaped for javascript #}
502
-        {{ var|escape('js') }} {# won't be double-escaped #}
499
+        {% autoescape 'js' %}
500
+            {{ var|escape('html') }} {# will be escaped for html and javascript #}
501
+            {{ var }} {# will be escaped for javascript #}
502
+            {{ var|escape('js') }} {# won't be double-escaped #}
503 503
         {% endautoescape %}
504 504
 
505 505
 .. note::
... ...
@@ -57,4 +57,31 @@ The ``escape`` filter supports the following escaping strategies:
57 57
     Internally, ``escape`` uses the PHP native `htmlspecialchars`_ function
58 58
     for the HTML escaping strategy.
59 59
 
60
+.. caution::
61
+
62
+    When using automatic escaping, Twig tries to not double-escape a variable
63
+    when the automatic escaping strategy is the same as the one applied by the
64
+    escape filter; but that does not work when using a variable as the
65
+    escaping strategy:
66
+
67
+    .. code-block:: jinja
68
+
69
+        {% set strategy = 'html' %}
70
+
71
+        {% autoescape 'html' %}
72
+            {{ var|escape('html') }}   {# won't be double-escaped #}
73
+            {{ var|escape(strategy) }} {# will be double-escaped #}
74
+        {% endautoescape %}
75
+
76
+    When using a variable as the escaping strategy, you should disable
77
+    automatic escaping::
78
+
79
+    .. code-block:: jinja
80
+
81
+        {% set strategy = 'html' %}
82
+
83
+        {% autoescape 'html' %}
84
+            {{ var|escape(strategy)|raw }} {# won't be double-escaped #}
85
+        {% endautoescape %}
86
+
60 87
 .. _`htmlspecialchars`: http://php.net/htmlspecialchars