Symfony 1.4, 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-32.

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

generator:
  class: sfPropelGenerator
  param:
    model_class:           BlogArticulo
    theme:                 admin
    non_verbose_templates: true
    with_show:             false
    singular:              BlogArticulo
    plural:                BlogArticulos
    route_prefix:          blog_articulo
    with_propel_route:     1
    actions_base_class:    sfActions
    css:                   mihojadeestilos

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

14.4.2. Creando una cabecera y un pie propios

Las vistas list, new 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
    _form_header.php
    _form_footer.php

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

Listado 14-33 - Ejemplo de elemento parcial para la cabecera de la vista edit, en modules/articulo/templates/_form_header.php

<?php if ($blog_articulo->getNumeroComentarios() > 0): ?>
  <h2>Este artículo tiene <?php echo $articulo->getNumeroComentarios() ?> comentarios.</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 subconjunto 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 sfConfig::get('sf_symfony_lib_dir')/plugins/sfPropelPlugin/data/generator/sfPropelModule/admin/.

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

// Elementos parciales, en [nombre_tema]/template/templates/
_assets.php
_filters.php
_filters_field.php
_flashes.php
_form.php
_form_actions.php
_form_field.php
_form_fieldset.php
_form_footer.php
_form_header.php
_list.php
_list_actions.php
_list_batch_actions.php
_list_field_boolean.php
_list_footer.php
_list_header.php
_list_td_actions.php
_list_td_batch_actions.php
_list_td_stacked.php
_list_td_tabular.php
_list_th_stacked.php
_list_th_tabular.php
_pagination.php
editSuccess.php
indexSuccess.php
newSuccess.php


// Acciones, en [nombre_tema]/parts
actionsConfiguration.php
batchAction.php
configuration.php
createAction.php
deleteAction.php
editAction.php
fieldsConfiguration.php
filterAction.php
filtersAction.php
filtersConfiguration.php
indexAction.php
newAction.php
paginationAction.php
paginationConfiguration.php
processFormAction.php
sortingAction.php
sortingConfiguration.php
updateAction.php

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-34 muestra un trozo de una de las "plantillas de plantillas" de Symfony.

Listado 14-34 - Sintaxis de las plantillas de plantillas

<h1>[?php echo <?php echo $this->getI18NString('edit.title') ?> ?]</h1>

[?php include_partial('<?php echo $this->getModuleName() ?>/flashes') ?]

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:

<h1><?php echo __('Listado de todos los artículos') ?></h1>

<?php include_partial('articulo/flashes') ?>

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 admin, modificarlo poco a poco y probar los cambios continuamente.

Nota También es posible encapsular 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.