Symfony 2.3, el libro oficial

7.8. Modificando las plantillas de los bundles

La comunidad de Symfony2 ha creado un montón de bundles de calidad que cubren las necesidades más comunes de las aplicaciones web. El problema es que cuando utilizas un bundle desarrollado por terceros, seguramente tendrás que modificar o personalizar alguna de sus plantillas.

Imagina que tu proyecto utiliza un bundle llamado AcmeBlogBundle (instalado como es habitual en la ruta src/Acme/BlogBundle). Aunque te gusta mucho cómo funciona, necesitas modificar el código HTML de la portada del blog para que se adapte mejor al diseño de tu aplicación. Observando el código del controlador Blog de ese bundle AcmeBlogBundle, encuentras lo siguiente:

public function indexAction()
{
    // obtener los artículos de alguna manera
    $blogs = ...;

    $this->render(
        'AcmeBlogBundle:Blog:index.html.twig',
        array('blogs' => $blogs)
    );
}

Cuando la aplicación renderiza la plantilla AcmeBlogBundle:Blog:index.html.twig, en realidad Symfony2 busca la plantilla en dos directorios diferentes:

  1. app/Resources/AcmeBlogBundle/views/Blog/index.html.twig
  2. src/Acme/BlogBundle/Resources/views/Blog/index.html.twig

Para sustituir la plantilla del paquete, sólo tienes que copiar la plantilla index.html.twig del bundle a app/Resources/AcmeBlogBundle/views/Blog/index.html.twig (el directorio app/Resources/AcmeBlogBundle no existe, por lo que tendrás que crearlo). Ahora ya puedes personalizar la plantilla para que se adapte mejor a tu aplicación.

Advertencia Si añades una plantilla en un nuevo directorio, seguramente tendrás que vaciar la caché (con php app/console cache:clear), incluso aunque tengas activado el modo debug (es decir, incluso aunque accedas a la aplicación en el entorno de desarrollo).

Esta lógica también se aplica a las plantillas base del bundle. Supongamos que todas las plantillas de AcmeBlogBundle heredan de una plantilla base llamada AcmeBlogBundle::layout.html.twig. Al igual que antes, Symfony2 busca esa plantilla en los dos siguientes directorios:

  1. app/Resources/AcmeBlogBundle/views/layout.html.twig
  2. src/Acme/BlogBundle/Resources/views/layout.html.twig

Al igual que en el caso anterior, para sustituir la plantilla sólo tienes que copiarla desde el bundle a app/Resources/AcmeBlogBundle/views/layout.html.twig. Y ahora ya puedes modificar la plantilla para que se adapte mejor al diseño de tu aplicación.

Como puedes observar, Symfony2 siempre empieza a buscar una plantilla en el directorio app/Resources/{NOMBRE_BUNDLE}/views/. Si la plantilla no existe, continúa buscando dentro del directorio Resources/views del propio bundle. Esto significa que todas las plantillas de todos los bundles se pueden sustituir colocándolas en el subdirectorio app/Resources adecuado.

7.8.1. Modificando las plantillas propias de Symfony

Como el propio framework Symfony2 está formado por bundles, también puedes modificar cualquiera de sus plantillas. El bundle TwigBundle por ejemplo contiene varias plantillas para mostrar las páginas de error y las páginas con excepciones. Para modificarlas, copia el contenido del directorio Resources/views/Exception del bundle TwigBundle al directorio app/Resources/TwigBundle/views/Exception.