added documentation for traits

diff --git a/doc/templates.rst b/doc/templates.rst
index 72e866a..fd618f7 100644 (file)
--- a/doc/templates.rst
+++ b/doc/templates.rst
@@ -1467,6 +1467,99 @@ Twig can be easily extended. If you are looking for new tags or filters, have
 a look at the Twig official extension repository:
 http://github.com/fabpot/Twig-extensions.
 
+Horizontal Reuse
+----------------
+
+.. note::
+
+    Horizontal reuse is an advanced Twig feature that is hardly ever needed in
+    regular templates. It is mainly used by projects that need to make
+    template blocks reusable without using inheritance.
+
+Template inheritance is one of the most powerful Twig's feature but it is
+limited to single inheritance; a template can only extend one other template.
+This limitation makes template inheritance simple to understand and easy to
+debug:
+
+.. code-block:: jinja
+
+    {% extends "base.html" %}
+
+    {% block title %}{% endblock %}
+    {% block content %}{% endblock %}
+
+Horizontal reuse is a way to achieve the same goal as multiple inheritance,
+but without the associated complexity:
+
+.. code-block:: jinja
+
+    {% extends "base.html" %}
+
+    {% use "blocks.html" %}
+
+    {% block title %}{% endblock %}
+    {% block content %}{% endblock %}
+
+The ``use`` statement tells Twig to import the blocks defined in
+```blocks.html`` into the current template (it's like macros, but for blocks):
+
+.. code-block:: jinja
+
+    # blocks.html
+    {% block sidebar %}{% endblock %}
+
+In this example, the ``use`` statement imports the ``sidebar`` block into the
+main template. The code is exactly equivalent to the following one:
+
+.. code-block:: jinja
+
+    {% extends "base.html" %}
+
+    {% block sidebar %}{% endblock %}
+    {% block title %}{% endblock %}
+    {% block content %}{% endblock %}
+
+.. note::
+
+    The ``use`` tag only imports a template if it does not extend another
+    template, if it does not define macros, and if the body is empty. But it
+    can *use* other templates.
+
+The main template can also override any imported block. If the template
+already defines the ``sidebar`` block, then the one defined in ``blocks.html``
+is ignored. To avoid name conflicts, you can rename imported blocks:
+
+.. code-block:: jinja
+
+    {% extends "base.html" %}
+
+    {% use "blocks.html" with sidebar as base_sidebar %}
+
+    {% block sidebar %}{% endblock %}
+    {% block title %}{% endblock %}
+    {% block content %}{% endblock %}
+
+Renaming also allows you to simulate inheritance by calling the "parent" block
+(like what you would have done with ``parent()``):
+
+.. code-block:: jinja
+
+    {% extends "base.html" %}
+
+    {% use "blocks.html" with sidebar as parent_sidebar %}
+
+    {% block sidebar %}
+        {{ block('parent_sidebar') }}
+    {% endblock %}
+
+    {% block title %}{% endblock %}
+    {% block content %}{% endblock %}
+
+.. note::
+
+    You can use as many ``use`` statements as you want in any given template.
+    If two imported templates define the same block, the latest one wins.
+
 .. _`Twig`:                https://github.com/Anomareh/PHP-Twig.tmbundle
 .. _`Jinja syntax plugin`: http://jinja.pocoo.org/2/documentation/integration
 .. _`Twig syntax plugin`:  https://github.com/blogsh/Twig-netbeans