From: Fabien Potencier Date: Fri, 29 Apr 2011 06:25:03 +0000 (+0200) Subject: added documentation for traits X-Git-Url: http://git.silmor.de/gitweb/?a=commitdiff_plain;h=5ea7020aa0b5168d83df1d22332d8cf509413a1e;p=web%2Fkonrad%2Ftwig.git added documentation for traits --- diff --git a/doc/templates.rst b/doc/templates.rst index 72e866a..fd618f7 100644 --- 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