use

Note

La reutilización horizontal es una característica avanzada de Twig que rara vez se necesita en plantillas regulares. Se utiliza principalmente por proyectos que necesitan hacer que los bloques de plantilla sean reutilizables sin usar herencia.

La herencia de plantillas es una de las características más poderosas de Twig pero está limitada a herencia simple; una plantilla solo puede extender una otra plantilla. Esta limitación hace que la herencia de plantillas sea simple de entender y fácil de depurar:

{% extends "base.html.twig" %}

{% block title %}{% endblock %}
{% block content %}{% endblock %}

La reutilización horizontal es una forma de lograr el mismo objetivo que la herencia múltiple, pero sin la complejidad asociada:

{% extends "base.html.twig" %}

{% use "blocks.html.twig" %}

{% block title %}{% endblock %}
{% block content %}{% endblock %}

La sentencia use le dice a Twig que importe los bloques definidos en blocks.html.twig a la plantilla actual (es como las macros, pero para bloques):

{# blocks.html.twig #}
{% block sidebar %}{% endblock %}

En este ejemplo, la sentencia use importa el bloque sidebar a la plantilla principal. El código es mayormente equivalente al siguiente (los bloques importados no se muestran automáticamente):

{% extends "base.html.twig" %}

{% block sidebar %}{% endblock %}
{% block title %}{% endblock %}
{% block content %}{% endblock %}

Note

La etiqueta use solo importa una plantilla si no extiende otra plantilla, si no define macros y si el cuerpo está vacío. Pero puede usar otras plantillas.

Note

Debido a que las sentencias use se resuelven independientemente del contexto pasado a la plantilla, la referencia de la plantilla no puede ser una expresión.

La plantilla principal también puede sobrescribir cualquier bloque importado. Si la plantilla ya define el bloque sidebar, entonces el definido en blocks.html.twig se ignora. Para evitar conflictos de nombres, puedes renombrar bloques importados:

{% extends "base.html.twig" %}

{% use "blocks.html.twig" with sidebar as base_sidebar, title as base_title %}

{% block sidebar %}{% endblock %}
{% block title %}{% endblock %}
{% block content %}{% endblock %}

La función parent() determina automáticamente el árbol de herencia correcto, por lo que puede usarse al sobrescribir un bloque definido en una plantilla importada:

{% extends "base.html.twig" %}

{% use "blocks.html.twig" %}

{% block sidebar %}
    {{ parent() }}
{% endblock %}

{% block title %}{% endblock %}
{% block content %}{% endblock %}

En este ejemplo, parent() llamará correctamente al bloque sidebar de la plantilla blocks.html.twig.

Tip

El renombrado te permite simular herencia llamando al bloque "padre":

{% extends "base.html.twig" %}

{% use "blocks.html.twig" with sidebar as parent_sidebar %}

{% block sidebar %}
    {{ block('parent_sidebar') }}
{% endblock %}

Note

Puedes usar tantas sentencias use como quieras en cualquier plantilla dada. Si dos plantillas importadas definen el mismo bloque, gana la última.