From e850d9798049aaf282ab398583ae32544f3c0ab9 Mon Sep 17 00:00:00 2001
From: fabien <fabien@93ef8e89-cb99-4229-a87c-7fa0fa45744b>
Date: Sun, 18 Oct 2009 22:53:49 +0000
Subject: [PATCH] updated documentation for new features

git-svn-id: http://svn.twig-project.org/trunk@78 93ef8e89-cb99-4229-a87c-7fa0fa45744b
---
 doc/02-Twig-for-Template-Designers.markdown |   41 ++++++++++-
 doc/06-Recipes.markdown                     |  102 +++++++++++++++++++++++++++
 2 files changed, 141 insertions(+), 2 deletions(-)
 create mode 100644 doc/06-Recipes.markdown

diff --git a/doc/02-Twig-for-Template-Designers.markdown b/doc/02-Twig-for-Template-Designers.markdown
index 33c08ee..08da161 100644
--- a/doc/02-Twig-for-Template-Designers.markdown
+++ b/doc/02-Twig-for-Template-Designers.markdown
@@ -280,6 +280,24 @@ to variables from outer scopes:
       <li>{% block loop_item %}{{ item }}{% endblock %}</li>
     {% endfor %}
 
+### Block Shortcuts
+
+For blocks with few content, it's possible to have a shortcut syntax. The
+following constructs do the same:
+
+    [twig]
+    {% block title %}
+      {{ page_title|title }}
+    {% endblock %}
+
+-
+
+    [twig]
+    {% block title page_title|title %}
+
+Note that as soon as you specify a second argument it's treated as short block
+and Twig won't look for a closing tag.
+
 Import Context Behavior
 -----------------------
 
@@ -460,7 +478,7 @@ The macro can then be called at will:
 
     [twig]
     <p>{{ forms.input('username') }}</p>
-    <p>{{ forms.input('password', null, 'password') }}</p>
+    <p>{{ forms.input('password', none, 'password') }}</p>
 
 ### Filters
 
@@ -472,6 +490,25 @@ data. Just wrap the code in the special `filter` section:
       This text becomes uppercase
     {% endfilter %}
 
+You can also chain filters:
+
+    [twig]
+    {% filter lower|escape %}
+      <strong>SOME TEXT</strong>
+    {% endfilter %}
+
+It should returns `&lt;strong&gt;some text&lt;/strong&gt;`.
+
+### Assignments
+
+Inside code blocks you can also assign values to variables. Assignments use
+the `set` tag and can have multiple targets:
+
+    [twig]
+    {% set foo as 'foo' %}
+
+    {% set key, value as call_something() %}
+
 ### Extends
 
 The `extends` tag can be used to extend a template from another one. You can
@@ -527,7 +564,7 @@ Importing these macros in a template is as easy as using the `import` tag:
       <dt>Username</dt>
       <dd>{{ forms.input('username') }}</dd>
       <dt>Password</dt>
-      <dd>{{ forms.input('password', null, 'password') }}</dd>
+      <dd>{{ forms.input('password', none, 'password') }}</dd>
     </dl>
     <p>{{ forms.textarea('comment') }}</p>
 
diff --git a/doc/06-Recipes.markdown b/doc/06-Recipes.markdown
new file mode 100644
index 0000000..0acd3f1
--- /dev/null
+++ b/doc/06-Recipes.markdown
@@ -0,0 +1,102 @@
+Recipes
+=======
+
+Making a Layout conditional
+---------------------------
+
+Working with Ajax means that the same content is sometimes displayed as is,
+and sometimes decorated with a layout. But as Twig templates are compiled as
+PHP classes, wrapping an `extends` tag with an `if` tag does not work:
+
+    [twig]
+    {# this does not work #}
+
+    {% if request.ajax %}
+      {% extends "base.html" %}
+    {% endif %}
+
+    {% block content %}
+      This is the content to be displayed.
+    {% endblock %}
+
+One way to solve this problem is to have two different templates:
+
+    [twig]
+    {# index.html #}
+    {% extends "layout.html" %}
+
+    {% block content %}
+      {% include "index_for_ajax.html" %}
+    {% endblock %}
+
+
+    {# index_for_ajax.html #}
+    This is the content to be displayed.
+
+Now, the decision to display one of the template is the responsibility of the
+controller:
+
+    [php]
+    $twig->render($request->isAjax() ? 'index_for_ajax.html' : 'index.html');
+
+Making an Include dynamic
+-------------------------
+
+When including a template, its name does not need to be a string. For
+instance, the name can depend on the value of a variable:
+
+    [twig]
+    {% include var ~ '_foo.html' %}
+
+If `var` evaluates to `index`, the `index_foo.html` template will be
+rendered.
+
+As a matter of fact, the template name can be any valid expression, such as
+the following:
+
+    [twig]
+    {% include var|default('index') ~ '_foo.html' %}
+
+Customizing the Syntax
+----------------------
+
+Twig allows some syntax customization for the block delimiters. It's not
+recommended to use this feature as templates will be tied with your custom
+syntax. But for specific projects, it can make sense to change the defaults.
+
+To change the block delimiters, you need to create your own lexer object:
+
+    [php]
+    $twig = new Twig_Environment();
+
+    $lexer = new Twig_Lexer($twig, array(
+      'tag_comment'  => array('{#', '#}'),
+      'tag_block'    => array('{%', '%}'),
+      'tag_variable' => array('{{', '}}'),
+    ));
+    $twig->setLexer($lexer);
+
+Here are some configuration example that simulates some other template engines
+syntax:
+
+    [php]
+    // Ruby erb syntax
+    $lexer = new Twig_Lexer($twig, array(
+      'tag_comment'  => array('<%#', '%>'),
+      'tag_block'    => array('<%', '%>'),
+      'tag_variable' => array('<%=', '%>'),
+    ));
+
+    // SGML Comment Syntax
+    $lexer = new Twig_Lexer($twig, array(
+      'tag_comment'  => array('<!--#', '-->'),
+      'tag_block'    => array('<!--', '-->'),
+      'tag_variable' => array('${', '}'),
+    ));
+
+    // Smarty like
+    $lexer = new Twig_Lexer($twig, array(
+      'tag_comment'  => array('{*', '*}'),
+      'tag_block'    => array('{', '}'),
+      'tag_variable' => array('{$', '}'),
+    ));
-- 
1.7.2.5