added a new recipe

diff --git a/doc/api.rst b/doc/api.rst
index eef76ff..39e4ca2 100644 (file)
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -96,7 +96,9 @@ 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``, or ``false`` to disable).
+  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).
 
 * ``optimizations``: A flag that indicates which optimizations to apply
   (default to ``-1`` -- all optimizations are enabled; set it to ``0`` to
@@ -312,7 +314,7 @@ Escaper Extension
 ~~~~~~~~~~~~~~~~~
 
 The ``escaper`` extension adds automatic output escaping to Twig. It defines a
-new tag, ``autoescape``, and a new filter, ``raw``.
+tag, ``autoescape``, and a filter, ``raw``.
 
 When creating the escaper extension, you can switch on or off the global
 output escaping strategy::
@@ -334,9 +336,9 @@ Twig 1.8):
 .. code-block:: jinja
 
     {% autoescape 'html' %}
-      {{ var }}
-      {{ var|raw }}      {# var won't be escaped #}
-      {{ var|escape }}   {# var won't be double-escaped #}
+        {{ var }}
+        {{ var|raw }}      {# var won't be escaped #}
+        {{ var|escape }}   {# var won't be double-escaped #}
     {% endautoescape %}
 
 .. warning::

diff --git a/doc/intro.rst b/doc/intro.rst
index cad60b6..f75ff19 100644 (file)
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -146,7 +146,7 @@ filesystem loader::
 
     $loader = new Twig_Loader_Filesystem('/path/to/templates');
     $twig = new Twig_Environment($loader, array(
-      'cache' => '/path/to/compilation_cache',
+        'cache' => '/path/to/compilation_cache',
     ));
 
     echo $twig->render('index.html', array('name' => 'Fabien'));

diff --git a/doc/recipes.rst b/doc/recipes.rst
index ff4678a..34ae1f9 100644 (file)
--- a/doc/recipes.rst
+++ b/doc/recipes.rst
@@ -150,8 +150,7 @@ thanks to the magic ``__get()`` method; you just need to also implement the
     {
         public function __get($name)
         {
-            if ('title' == $name)
-            {
+            if ('title' == $name) {
                 return 'The title';
             }
 
@@ -160,8 +159,7 @@ thanks to the magic ``__get()`` method; you just need to also implement the
 
         public function __isset($name)
         {
-            if ('title' == $name)
-            {
+            if ('title' == $name) {
                 return true;
             }
 
@@ -317,4 +315,48 @@ This can be easily achieved with the following code::
         return $node;
     }
 
+Using the Template name to set the default Escaping Strategy
+------------------------------------------------------------
+
+.. versionadded:: 1.8
+    This recipe requires Twig 1.8 or later.
+
+The ``autoescape`` option determines the default escaping strategy to use when
+no escaping is applied on a variable. When Twig is used to mostly generate
+HTML files, you can set it to ``html`` and explicitly change it to ``js`` when
+you have some dynamic JavaScript files thanks to the ``autoescape`` tag::
+
+.. code-block:: jinja
+
+    {% autoescape js %}
+        ... some JS ...
+    {% endautoescape %}
+
+But if you have many HTML and JS files, and if your template names follow some
+conventions, you can instead determine the default escaping strategy to use
+based on the template name. Let's say that your template names always ends
+with ``.html`` for HTML files and ``.js`` for JavaScript ones, here is how you
+can configure Twig::
+
+    function twig_escaping_guesser($filename)
+    {
+        // get the format
+        $format = substr($filename, strrpos($filename, '.') + 1);
+
+        switch ($format) {
+            'js':
+                return 'js';
+            default:
+                return 'html';
+        }
+    }
+
+    $loader = new Twig_Loader_Filesystem('/path/to/templates');
+    $twig = new Twig_Environment($loader, array(
+        'autoescape' => 'twig_escaping_guesser',
+    ));
+
+This dynamic strategy does not incur any overhead at runtime as auto-escaping
+is done at compilation time.
+
 .. _callback: http://www.php.net/manual/en/function.is-callable.php