Traits are "special" templates that define blocks that you can "include" in
other templates.
Let's take an example:
{# 'foo' template defines the 'foo' block #}
{% block 'foo' %}
FOO
{% endblock %}
{# 'main' template defines the 'bar' block and include the 'foo' block from the 'foo' template #}
{% extends 'base' %}
{% use 'foo' %}
{% block 'bar' %}
BAR
{% endblock %}
In the previous example, the 'main' template use the 'foo' one. It means that
the 'foo' block defined in the 'foo' template is available as if it were
defined in the 'main' template.
You can use as many 'use' statements as you want in a template:
{% extends 'base' %}
{% use 'foo' %}
{% use 'bar' %}
{% use 'foobar' %}
If two templates define the same block, the latest one wins. The template can
also overrides any block.
The 'use' tag also supports "dynamic" names:
{% set foo = 'foo' %}
{% use foo %}
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:
{# 'foo' template #}
{% block 'foo' %}
FOO
{% endblock %}
{# 'bar' template #}
{% use 'foo' %}
{% block 'bar' %}
BAR
{% endblock %}
{# 'main' template #}
{% extends 'base' %}
{% use 'bar' %}
In this example, the 'main' template has access to both 'foo' and 'bar'.
Traits are mainly useful when you consider blocks as reusable "functions";
like we do in Symfony2 forms or if you use Twig for code generation.
* markstory/whitespace:
Updating documentation for whitespace trim tags.
Making trim tags consume all whitespace, both horizontal and vertical.
Adding additional test suggested by nikic.
Making a capturing group non capturing, as the group isn't used.
Moving newline trimming into the regexp used to match end of tags.
Applying changes suggested by nikic to simplify how end of comments are processed.
Fixing some whitespace.
Fixing typo.
Adding a bit of documentation for whitespace trimming.
Adding whitespace trimming support to other tag types (comments, variables) Refactoring how whitespace trimming is done, and moving it into a separate option that is combined with other tag types. Adding more tests. Refs #284
Fixing use of non-existent method name.
Adding a test case for mixing {%- and %} tags together.
Adding a test that uses tabs. Added a test for trailing tabs and -%} Refs #284
Implementing {%- which trims non-newline whitespace preceding it. Refs
nikic
Fabien Potencier
Joseph Bielawski
lenar
Mark Story
Jordi Boggiano