Browse code

added a new recipe

Fabien Potencier authored on 27/04/2012 12:18:22
Showing 3 changed files
... ...
@@ -96,7 +96,9 @@ The following options are available:
96 96
 
97 97
 * ``autoescape``: If set to ``true``, auto-escaping will be enabled by default
98 98
   for all templates (default to ``true``). As of Twig 1.8, you can set the
99
-  escaping strategy to use (``html``, ``js``, or ``false`` to disable).
99
+  escaping strategy to use (``html``, ``js``, ``false`` to disable, or a PHP
100
+  callback that takes the template "filename" and must return the escaping
101
+  strategy to use).
100 102
 
101 103
 * ``optimizations``: A flag that indicates which optimizations to apply
102 104
   (default to ``-1`` -- all optimizations are enabled; set it to ``0`` to
... ...
@@ -312,7 +314,7 @@ Escaper Extension
312 314
 ~~~~~~~~~~~~~~~~~
313 315
 
314 316
 The ``escaper`` extension adds automatic output escaping to Twig. It defines a
315
-new tag, ``autoescape``, and a new filter, ``raw``.
317
+tag, ``autoescape``, and a filter, ``raw``.
316 318
 
317 319
 When creating the escaper extension, you can switch on or off the global
318 320
 output escaping strategy::
... ...
@@ -334,9 +336,9 @@ Twig 1.8):
334 336
 .. code-block:: jinja
335 337
 
336 338
     {% autoescape 'html' %}
337
-      {{ var }}
338
-      {{ var|raw }}      {# var won't be escaped #}
339
-      {{ var|escape }}   {# var won't be double-escaped #}
339
+        {{ var }}
340
+        {{ var|raw }}      {# var won't be escaped #}
341
+        {{ var|escape }}   {# var won't be double-escaped #}
340 342
     {% endautoescape %}
341 343
 
342 344
 .. warning::
... ...
@@ -146,7 +146,7 @@ filesystem loader::
146 146
 
147 147
     $loader = new Twig_Loader_Filesystem('/path/to/templates');
148 148
     $twig = new Twig_Environment($loader, array(
149
-      'cache' => '/path/to/compilation_cache',
149
+        'cache' => '/path/to/compilation_cache',
150 150
     ));
151 151
 
152 152
     echo $twig->render('index.html', array('name' => 'Fabien'));
... ...
@@ -150,8 +150,7 @@ thanks to the magic ``__get()`` method; you just need to also implement the
150 150
     {
151 151
         public function __get($name)
152 152
         {
153
-            if ('title' == $name)
154
-            {
153
+            if ('title' == $name) {
155 154
                 return 'The title';
156 155
             }
157 156
 
... ...
@@ -160,8 +159,7 @@ thanks to the magic ``__get()`` method; you just need to also implement the
160 159
 
161 160
         public function __isset($name)
162 161
         {
163
-            if ('title' == $name)
164
-            {
162
+            if ('title' == $name) {
165 163
                 return true;
166 164
             }
167 165
 
... ...
@@ -317,4 +315,48 @@ This can be easily achieved with the following code::
317 315
         return $node;
318 316
     }
319 317
 
318
+Using the Template name to set the default Escaping Strategy
319
+------------------------------------------------------------
320
+
321
+.. versionadded:: 1.8
322
+    This recipe requires Twig 1.8 or later.
323
+
324
+The ``autoescape`` option determines the default escaping strategy to use when
325
+no escaping is applied on a variable. When Twig is used to mostly generate
326
+HTML files, you can set it to ``html`` and explicitly change it to ``js`` when
327
+you have some dynamic JavaScript files thanks to the ``autoescape`` tag::
328
+
329
+.. code-block:: jinja
330
+
331
+    {% autoescape js %}
332
+        ... some JS ...
333
+    {% endautoescape %}
334
+
335
+But if you have many HTML and JS files, and if your template names follow some
336
+conventions, you can instead determine the default escaping strategy to use
337
+based on the template name. Let's say that your template names always ends
338
+with ``.html`` for HTML files and ``.js`` for JavaScript ones, here is how you
339
+can configure Twig::
340
+
341
+    function twig_escaping_guesser($filename)
342
+    {
343
+        // get the format
344
+        $format = substr($filename, strrpos($filename, '.') + 1);
345
+
346
+        switch ($format) {
347
+            'js':
348
+                return 'js';
349
+            default:
350
+                return 'html';
351
+        }
352
+    }
353
+
354
+    $loader = new Twig_Loader_Filesystem('/path/to/templates');
355
+    $twig = new Twig_Environment($loader, array(
356
+        'autoescape' => 'twig_escaping_guesser',
357
+    ));
358
+
359
+This dynamic strategy does not incur any overhead at runtime as auto-escaping
360
+is done at compilation time.
361
+
320 362
 .. _callback: http://www.php.net/manual/en/function.is-callable.php