include

La sentencia include incluye una plantilla y muestra el contenido renderizado de ese archivo:

{% include 'header.html.twig' %}
    Cuerpo
{% include 'footer.html.twig' %}

Note

Se recomienda usar la función include en su lugar, ya que proporciona las mismas características con un poco más de flexibilidad:

  • La función include es semánticamente más "correcta" (incluir una plantilla muestra su contenido renderizado en el ámbito actual; una etiqueta no debería mostrar nada);
  • La función include es más "componible":
{# Almacenar una plantilla renderizada en una variable #}
{% set content %}
    {% include 'template.html.twig' %}
{% endset %}
{# vs #}
{% set content = include('template.html.twig') %}

{# Aplicar filtro en una plantilla renderizada #}
{% apply upper %}
    {% include 'template.html.twig' %}
{% endapply %}
{# vs #}
{{ include('template.html.twig')|upper }}
  • La función include no impone ningún orden específico para los argumentos gracias a argumentos con nombre.

Las plantillas incluidas tienen acceso a las variables del contexto activo.

Si estás usando el cargador del sistema de archivos, las plantillas se buscan en las rutas definidas por él.

Puedes agregar variables adicionales pasándolas después de la palabra clave with:

{# template.html.twig tendrá acceso a las variables del contexto actual y las adicionales proporcionadas #}
{% include 'template.html.twig' with {'name': 'Fabien'} %}

{% set vars = {'name': 'Fabien'} %}
{% include 'template.html.twig' with vars %}

Puedes deshabilitar el acceso al contexto agregando la palabra clave only:

{# solo la variable name será accesible #}
{% include 'template.html.twig' with {'name': 'Fabien'} only %}
{# ninguna variable será accesible #}
{% include 'template.html.twig' only %}

Tip

Cuando incluyas una plantilla creada por un usuario final, deberías considerar ponerla en un sandbox. Más información en el capítulo Twig Sandbox.

El nombre de la plantilla puede ser cualquier expresión válida de Twig:

{% include some_var %}
{% include ajax ? 'ajax.html.twig' : 'not_ajax.html.twig' %}

Y si la expresión se evalúa como una instancia de \Twig\Template o \Twig\TemplateWrapper, Twig la usará directamente:

// {% include template %}

$template = $twig->load('some_template.html.twig');

$twig->display('template.html.twig', ['template' => $template]);

Puedes marcar una inclusión con ignore missing en cuyo caso Twig ignorará la sentencia si la plantilla a incluir no existe. Debe colocarse justo después del nombre de la plantilla. Aquí algunos ejemplos válidos:

{% include 'sidebar.html.twig' ignore missing %}
{% include 'sidebar.html.twig' ignore missing with {'name': 'Fabien'} %}
{% include 'sidebar.html.twig' ignore missing only %}

También puedes proporcionar una lista de plantillas que se verifican por existencia antes de la inclusión. Se incluirá la primera plantilla que exista:

{% include ['page_detailed.html.twig', 'page.html.twig'] %}

Si se da ignore missing, volverá a no renderizar nada si ninguna de las plantillas existe, de lo contrario lanzará una excepción.