Symfony 1.1, la guía definitiva

14.4. Modificando el aspecto de los módulos generados

La presentación de los módulos generados se puede modificar completamente para integrarlo con cualquier otro estilo gráfico. Los cambios no solo se pueden realizar mediante una hoja de estilos, sino que es posible redefinir las plantillas por defecto.

14.4.1. Utilizando una hoja de estilos propia

Como el código HTML generado tiene un contenido bien estructurado, es posible modificar fácilmente su aspecto.

Mediante la opción css de la configuración del generador es posible definir la hoja de estilos alternativa que se utiliza en el módulo de administración, como se muestra en el listado 14-38.

Listado 14-38 - Utilizando una hoja de estilos propia en vez de la de por defecto

generator:
      class:              sfPropelAdminGenerator
      param:
        model_class:      Comment
        theme:            default
        css:              mystylesheet

Además, también es posible utilizar las opciones habituales del archivo view.yml del módulo para redefinir los estulos utilizados en cada vista.

14.4.2. Creando una cabecera y un pie propios

Las vistas list y edit incluyen por defecto elementos parciales para la cabecera y el pie de página. Como no existen por defecto elementos parciales en el directorio templates/ del módulo de administración, solamente es necesario crearlos con los siguientes nombres para que se incluyan de forma automática:

_list_header.php
    _list_footer.php
    _edit_header.php
    _edit_footer.php

Si se quiere añadir por ejemplo una cabecera propia en la vista article/edit, se crea un archivo llamado _edit_header.php como el que muestra el listado 14-39. No es necesario realizar más configuraciones para que se incluya automáticamente.

Listado 14-39 - Ejemplo de elemento parcial para la cabecera de la vista edit, en modules/articles/templates/_edit_header.php

<?php if ($article->getNbComments() > 0): ?>
      <h2>This article has <?php echo $article->getNbComments() ?> comments.</h2>
    <?php endif; ?>

Debe tenerse en cuenta que un elemento parcial de la vista edit siempre tiene acceso al objeto al que hace referencia mediante una variable con el mismo nombre que la clase y que un elemento parcial de la vista list tiene acceso al paginador actual mediante la variable $pager.

14.4.3. Modificando el tema

Existen otros elementos parciales en el directorio templates/ del módulo que heredan del framework y que se pueden redefinir para adaptarse a las necesidades de cada proyecto.

Las plantillas del generador están divididas en pequeñas partes que se pueden redefinir de forma independiente, al igual que se pueden modificar las acciones una a una.

No obstante, si se quieren redefinir todos los elementos parciales para varios módulos, lo mejor es crear un tema que se pueda reutilizar. Un tema es un conjunto completo de plantillas y acciones que se pueden utilizar en un módulo de administración si así se indica en el archivo generator.yml. En el tema por defecto, Symfony utiliza los archivos definidos en $sf_symfony_lib_dir/plugins/sfPropelPlugin/data/generator/sfPropelAdmin/default/.

Los archivos de los temas tienen que guardarse en el directorio data/generator/sfPropelAdmin/[nombre_tema]/template/ del proyecto, y la mejor forma de crear un nuevo tema consiste en copiar los archivos del tema por defecto (que se encuentran en el directorio $sf_symfony_lib_dir/plugins/sfPropelPlugin/data/generator/sfPropelAdmin/default/template/). De esta forma, es fácil asegurarse de que el tema propio contiene todos los archivos requeridos:

// Elementos parciales, en [nombre_tema]/template/templates/
    _edit_actions.php
    _edit_footer.php
    _edit_form.php
    _edit_header.php
    _edit_messages.php
    _filters.php
    _list.php
    _list_actions.php
    _list_footer.php
    _list_header.php
    _list_messages.php
    _list_td_actions.php
    _list_td_stacked.php
    _list_td_tabular.php
    _list_th_stacked.php
    _list_th_tabular.php

    // Acciones, en [nombre_tema]/template/actions/actions.class.php
    processFilters()     // Procesa los filtros de la petición
    addFiltersCriteria() // Añade un filtro al objeto Criteria
    processSort()
    addSortCriteria()

Se debe tener en cuenta que los archivos de las plantillas son en realidad "plantillas de plantillas", es decir, archivos PHP que se procesan mediante una herramienta especial para generar las plantillas en función de las opciones del generador (este proceso se conoce como la fase de compilación). Como las plantillas generadas deben contener código PHP que se ejecuta cuando se accede a estas plantillas, los archivos que son "plantillas de plantillas" tienen que utilizar una sintaxis alternativa para que el código PHP final no se ejecute durante el proceso de compilación de las plantillas. El listado 14-40 muestra un trozo de una de las "plantillas de plantillas" de Symfony.

Listado 14-40 - Sintaxis de las plantillas de plantillas

<?php foreach ($this->getPrimaryKey() as $pk): ?>
    [?php echo object_input_hidden_tag($<?php echo $this->getSingularName() ?>,'get<?php echo $pk->getPhpName() ?>') ?]
    <?php endforeach; ?>

En el listado anterior, el código PHP indicado mediante <? se ejecuta durante la compilación, mientras que el código indicado mediante [? se ejecuta solamente durante la ejecución final de la plantilla generada. El generador de plantillas reemplaza las etiquetas [? en etiquetas <?, por lo que la plantilla resultante es la siguiente:

<?php echo object_input_hidden_tag($article, 'getId') ?>

Trabajar con las "plantillas de plantillas" es bastante complicado, por lo que el mejor consejo para crear un tema propio es comenzarlo a partir del tema default, modificarlo poco a poco y probar los cambios continuamente.

Truco También es posible encapsultar un tema completo para el generador en un plugin, con lo que el tema es más fácil de reutilizar y más fácil de instalar en diferentes aplicaciones. El Capítulo 17 incluye más información.