Permalink
Browse files

added support for more escaping strategies (url, css, and html_attr)

  • Loading branch information...
fabpot committed Jun 27, 2012
1 parent cd049da commit 7657c01e65695a9a53cf63e0d8e4b872ce00451b
View
@@ -1,5 +1,6 @@
-* 1.8.4 (2012-XX-XX)
+* 1.9.0 (2012-XX-XX)
+ * added escaping strategies for CSS, URL, and HTML attributes
* fixed nested embed tag calls
* added the date_modify filter
View
@@ -96,10 +96,10 @@ The following options are available:
* ``autoescape``: If set to ``true``, auto-escaping will be enabled by default
for all templates (default to ``true``). As of Twig 1.8, you can set the
- escaping strategy to use (``html``, ``js``, ``false`` to disable, or a PHP
- callback that takes the template "filename" and must return the escaping
- strategy to use -- the callback cannot be a function name to avoid collision
- with built-in escaping strategies).
+ escaping strategy to use (``html``, ``js``, ``css``, ``false`` to disable,
+ or a PHP callback that takes the template "filename" and must return the
+ escaping strategy to use -- the callback cannot be a function name to avoid
+ collision with built-in escaping strategies).
* ``optimizations``: A flag that indicates which optimizations to apply
(default to ``-1`` -- all optimizations are enabled; set it to ``0`` to
@@ -1,8 +1,8 @@
``date_modify``
===============
-.. versionadded:: 1.8.4
- The date_modify filter has been added in Twig 1.8.4.
+.. versionadded:: 1.9.0
+ The date_modify filter has been added in Twig 1.9.0.
The ``date_modify`` filter modifies a date with a given modifier string:
View
@@ -1,9 +1,15 @@
``escape``
==========
-The ``escape`` filter converts the characters ``&``, ``<``, ``>``, ``'``, and
-``"`` in strings to HTML-safe sequences. Use this if you need to display text
-that might contain such characters in HTML:
+.. versionadded:: 1.9.0
+ The ``css``, ``url``, and ``html_attr`` strategies were added in Twig
+ 1.9.0.
+
+The ``escape`` filter escapes a string for safe insertion into the final
+output. It supports different escaping strategies depending on the template
+context.
+
+By default, it uses the HTML escaping strategy:
.. code-block:: jinja
@@ -31,6 +37,21 @@ And here is how to escape variables included in JavaScript code:
{{ user.username|escape('js') }}
{{ user.username|e('js') }}
+The ``escape`` filter supports the following escaping strategies:
+
+* ``html``: escapes a string for the **HTML body** context.
+
+* ``js``: escapes a string for the **JavaScript context**.
+
+* ``css``: escapes a string for the **CSS context**. CSS escaping can be
+ applied to any string being inserted into CSS and escapes everything except
+ alphanumerics.
+
+* ``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.
+
.. note::
Internally, ``escape`` uses the PHP native `htmlspecialchars`_ function
View
@@ -371,16 +371,24 @@ Twig supports both, automatic escaping is enabled by default.
Working with Manual Escaping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If manual escaping is enabled it's **your** responsibility to escape variables
-if needed. What to escape? If you have a variable that *may* include any of
-the following chars (``>``, ``<``, ``&``, or ``"``) you **have to** escape it
-unless the variable contains well-formed and trusted HTML. Escaping works by
-piping the variable through the :doc:`escape<filters/escape>` or ``e`` filter:
+If manual escaping is enabled, it is **your** responsibility to escape
+variables if needed. What to escape? Any variable you don't trust.
+
+Escaping works by piping the variable through the
+:doc:`escape<filters/escape>` or ``e`` filter:
.. code-block:: jinja
{{ user.username|e }}
+
+By default, the ``escape`` filter uses the ``html`` strategy, but depending on
+the escaping context, you might want to explicitly use any other available
+strategies:
+
{{ user.username|e('js') }}
+ {{ user.username|e('css') }}
+ {{ user.username|e('url') }}
+ {{ user.username|e('html_attr') }}
Working with Automatic Escaping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -391,8 +399,18 @@ tag:
.. code-block:: jinja
- {% autoescape true %}
- Everything will be automatically escaped in this block
+ {% autoescape %}
+ Everything will be automatically escaped in this block (using the HTML strategy)
+ {% endautoescape %}
+
+By default, auto-escaping uses the ``html`` escaping strategy. If you output
+variables in other contexts, you need to explicitly escape them with the
+appropriate escaping strategy:
+
+.. code-block:: jinja
+
+ {% autoescape 'js' %}
+ Everything will be automatically escaped in this block (using the JS strategy)
{% endautoescape %}
Escaping
View
@@ -15,7 +15,7 @@
#ifndef PHP_TWIG_H
#define PHP_TWIG_H
-#define PHP_TWIG_VERSION "1.8.4-DEV"
+#define PHP_TWIG_VERSION "1.9.0-DEV"
#include "php.h"
View
@@ -17,7 +17,7 @@
*/
class Twig_Environment
{
- const VERSION = '1.8.4-DEV';
+ const VERSION = '1.9.0-DEV';
protected $charset;
protected $loader;
Oops, something went wrong.

0 comments on commit 7657c01

Please sign in to comment.