From c04d119d101ecf1d45bfbf3f6eb76b86f4806aea Mon Sep 17 00:00:00 2001 From: Arnaud Le Blanc Date: Sun, 7 Nov 2010 18:23:31 +0100 Subject: [PATCH] update docs for automatic escaping --- doc/02-Twig-for-Template-Designers.markdown | 3 +- doc/03-Twig-for-Developers.markdown | 45 ++++++++++++++++++-------- doc/04-Extending-Twig.markdown | 14 +++----- 3 files changed, 38 insertions(+), 24 deletions(-) diff --git a/doc/02-Twig-for-Template-Designers.markdown b/doc/02-Twig-for-Template-Designers.markdown index fa300a9..f326697 100644 --- a/doc/02-Twig-for-Template-Designers.markdown +++ b/doc/02-Twig-for-Template-Designers.markdown @@ -1233,7 +1233,8 @@ might contain such characters in HTML. ### `raw` The `raw` filter marks the value as safe which means that in an environment -with automatic escaping enabled this variable will not be escaped. +with automatic escaping enabled this variable will not be escaped if `raw` is +the last filter applied to it. [twig] {% autoescape on } diff --git a/doc/03-Twig-for-Developers.markdown b/doc/03-Twig-for-Developers.markdown index 9dfb23b..7867abc 100644 --- a/doc/03-Twig-for-Developers.markdown +++ b/doc/03-Twig-for-Developers.markdown @@ -327,7 +327,7 @@ You can also change the escaping mode locally by using the `autoescape` tag: >The `autoescape` tag has no effect on included files. The escaping rules are implemented as follows (it describes the behavior of -Twig 0.9.5 and above): +Twig 0.9.9 and above): * Literals (integers, booleans, arrays, ...) used in the template directly as variables or filter arguments are never automatically escaped: @@ -338,28 +338,45 @@ Twig 0.9.5 and above): {% set text = "Twig
" %} {{ text }} {# will be escaped #} - * Escaping is applied before any other filter is applied (the reasoning - behind this is that filter transformations should be safe, as the filtered - value and all its arguments are escaped): + * Expressions which the result is always a literal or a variable marked safe + are never automatically escaped: [twig] - {{ var|nl2br }} {# is equivalent to {{ var|escape|nl2br }} #} + {{ foo ? "Twig
" : "
Twig" }} {# won't be escaped #} - * The `raw` filter can be used anywhere in the filter chain: + {% set text = "Twig
" %} + {{ foo ? text : "
Twig" }} {# will be escaped #} + + {% set text = "Twig
" %} + {{ foo ? text|raw : "
Twig" }} {# won't be escaped #} + + {% set text = "Twig
" %} + {{ foo ? text|escape : "
Twig" }} {# won't be escaped #} + + * Escaping is applied before printing, after any other filter is applied: [twig] - {{ var|upper|nl2br|raw }} {# is equivalent to {{ var|raw|upper|nl2br }} #} + {{ var|upper }} {# is equivalent to {{ var|upper|escape }} #} + + * The `raw` filter should only be used at the end of the filter chain: - * Automatic escaping is applied to filter arguments, except for literals: + [twig] + {{ var|raw|upper }} {# will be escaped #} [twig] - {{ var|foo("bar") }} {# "bar" won't be escaped #} - {{ var|foo(bar) }} {# bar will be escaped #} - {{ var|foo(bar|raw) }} {# bar won't be escaped #} + {{ var|upper|raw }} {# won't be escaped #} - * Automatic escaping is not applied if one of the filters in the chain has the - `is_escaper` option set to `true` (this is the case for the built-in - `escaper`, `raw`, and `urlencode` filters for instance). + * Automatic escaping is not applied if the last filter in the chain is marked + safe for the current context (e.g. `html` or `js`). `escaper` and + `escaper('html')` are marked safe for html, `escaper('js')` is marked safe + for javascript, `raw` is marked safe for everything. + + [twig] + {% autoescape js on %} + {{ var|escape('html') }} {# will be escaped for html and javascript #} + {{ var }} {# will be escaped for javascript #} + {{ var|escape('js') }} {# won't be double-escaped #} + {% endautoescape %} ### Sandbox Extension diff --git a/doc/04-Extending-Twig.markdown b/doc/04-Extending-Twig.markdown index eee93af..f6d4833 100644 --- a/doc/04-Extending-Twig.markdown +++ b/doc/04-Extending-Twig.markdown @@ -335,17 +335,13 @@ filter call: ### Automatic Escaping -If automatic escaping is enabled, the main value passed to the filters is -automatically escaped. If your filter acts as an escaper, you will want the -raw variable value. In such a case, set the `is_escaper` option to `true`: +If automatic escaping is enabled, the output of the filter may be escaped before +printing. If your filter acts as an escaper (or explicitly outputs html or +javascript code), you will want the raw output to be printed. In such a case, +set the `is_safe` option: [php] - $filter = new Twig_Filter_Function('urlencode', array('is_escaper' => true)); - ->**NOTE** ->The parameters passed as extra arguments to the filters are not affected by ->the `is_escaper` option and they are always escaped according to the ->automatic escaping rules. + $filter = new Twig_Filter_Function('nl2br', array('is_safe' => array('html'))); Overriding default Filters -------------------------- -- 1.7.2.5