Twig: Etiquetas include y embed para insertar plantillas

Twig, al igual que otros motores de plantillas, posee etiquetas para incluir en nuestras páginas diferentes archivos y construir las vistas a partir de trozos de código más pequeños y reutilizables. En este artículo quiero hablar sobre las diferentes maneras que tenemos de insertar en una vista otros archivos de plantilla.

Quien haya usado Twig en algún proyecto ya estará familiarizado con las etiquetas block  y extends entre otras, así que en este artículo suponemos que ya se conocen los principios de funcionamiento de este motor.

Las etiquetas de las que vamos a hablar en concreto son include embed.

Twig include

Esta etiqueta es de las más utilizadas. Podemos compararla con la sentencia PHP de mismo nombre, ya que su función es la de insertar otro archivo de plantilla dentro de la actual.

Gracias a ella nos es muy fácil evitar la duplicidad del código en las vistas con los problemas que esto acarrea a la larga. Es tan fácil como extraer el código que vemos que debe repetirse en otro lugar a un archivo independiente, y posteriormente realizaremos la llamada a este archivo mediante include.

El modo de empleo es el siguiente:

No tiene etiqueta de cierre ya que no puede tener nunca cuerpo, simplemente la ruta a la plantilla que se incluye dentro.

Además de esta funcionalidad base, podemos añadirle algo más. Para ello, imaginemos ahora que creamos un archivo para volcar un formulario y lo utilizamos en varias vistas. En nuestro archivo a incluir, el formulario está almacenado en una variable de nombre form, mientras que en la vista actual el formulario se llama edit_form. Si intentamos hacer un include, Twig nos devolverá un error al no tener definida la variable en cuestión.

Aunque podemos crear en la propia plantilla las variables con el nombre requerido antes de incluir el archivo, esto no es una buena solución. Estamos añadiendo más variables al ámbito global y en algunos casos de plantillas complejas podríamos acabar pisando unas variables con otras. Por ese motivo, Twig nos permite enviar variables en el propio include donde podemos aprovechar para establecer el nombre deseado:

Recuerda que puedes enviar múltiples variables separadas por coma o un array asociativo definido previamente.

Sin embargo también podríamos encontrar una situación distinta, en la cual no deseemos que nuestro archivo incluido pueda acceder a las variables definidas en el archivo que le llama. Para estos casos, deberemos indicarlo en la llamada mediante la palabra only:

Estas son las posibilidades que nos ofrece include, que servirá para cubrir la mayoría de situaciones. Puedes consultar la documentación oficial aquí.

Twig embed

¿Has probado a sustituir un bloque definido en una plantilla llamada mediante include? Si no se te ha presentado la ocasión, haz la prueba y verás que no puedes sobrescribir el contenido.

Para solventar esto tenemos a nuestra disposición la etiqueta embed, que en la documentación oficial la definen como una fusión entres include extends.

Aquí te dejo un ejemplo para incluir una tabla sustituyendo bloques:

Con estas dos etiquetas podrás hacer todas las combinaciones que desees y tener el código de tus vistas estructurado y sin duplicidades que es uno de los objetivos que debemos perseguir siempre en nuestros proyectos.