Symfony 1.4, la guía definitiva

14.2. Creando la parte de administración de las aplicaciones

Symfony es capaz de generar módulos más avanzados para la parte de gestión o administración de las aplicaciones, también basados en las definiciones de las clases del modelo del archivo schema.yml. Se puede crear toda la parte de administración de la aplicación mediante módulos generados automáticamente. Los ejemplos de esta sección describen los módulos de administración creados para una aplicación llamada backend. El esqueleto de la aplicación se puede crear mediante la tarea generate:app de Symfony:

$ php symfony generate:app backend

Los módulos de administración interpretan el modelo con la ayuda de un archivo de configuración especial llamado generator.yml, que se puede modificar para extender los componentes generados automáticamente y para controlar el aspecto visual de los módulos. Este tipo de módulos también disponen de los mecanismos habituales descritos en los capítulos anteriores (layout, enrutamiento, configuración propia, carga automática de clases, etc.). Incluso es posible redefinir las acciones y plantillas generadas para incluir características propias, aunque el archivo generator.yml es suficiente para realizar la mayoría de modificaciones, por lo que el código PHP solamente es necesario para las tareas muy específicas.

Nota Aunque las funcionalidades más utilizadas se configuran en el archivo generator.yml, los módulos de administración también se pueden configurar mediante una clase de configuración, como se verá más adelante en este capítulo.

14.2.1. Iniciando un módulo de administración

Symfony crea la parte de administración de una aplicación en base a su modelo de datos. Los módulos se generan a partir de objetos Propel o Doctrine:

// Propel
$ php symfony propel:generate-admin backend BlogArticulo --module=articulo

// Doctrine
$ php symfony doctrine:generate-admin backend BlogArticulo --module=articulo

Nota Los módulos de administración se basan en una arquitectura de tipo REST. La tarea propel:generate-admin añade una ruta apropiada para esa arquitectura en el archivo de configuración routing.yml:

# apps/backend/config/routing.yml
article:
  class: sfPropelRouteCollection
  options:
    model:                BlogArticulo
    module:               articulo
    with_wildcard_routes: true

También es posible crear tu propia ruta y pasar su nombre como argumento de la tarea en vez del nombre de la clase del modelo:

$ php symfony propel:generate-admin backend articulo --module=article

Después de ejecutar el comando anterior, se crea un módulo llamado articulo en la aplicación backend y basado en la definición de la clase BlogArticulo, que además es accesible desde la dirección:

http://localhost/backend.php/articulo

El aspecto gráfico del módulo generado, que se muestra en las figuras 14-2 y 14-3, es suficientemente avanzado como para utilizarlo en la mayoría de aplicaciones comerciales.

Nota Si el aspecto gráfico de la aplicación no es el que esperabas (no se aplican las hojas de estilos y no se ven las imágenes) ejecuta la tarea plugin:publish-assets para instalar esos archivos web (CSS, imágenes) en el proyecto:

$ php symfony plugin:publish-assets
Vista "list" del módulo "articulo" en la aplicación "backend"

Figura 14.2 Vista "list" del módulo "articulo" en la aplicación "backend"

Vista "edit" del módulo "articulo" en la aplicación "backend"

Figura 14.3 Vista "edit" del módulo "articulo" en la aplicación "backend"

14.2.2. Un vistazo al código generado

El código del módulo de administración articulo, que se encuentra en el directorio apps/backend/modules/articulo/, está completamente vacío porque sólo ha sido iniciado. La mejor forma de comprobar el código generado para este módulo es acceder con el navegador a sus páginas y después comprobar los contenidos de la carpeta cache/. El listado 14-2 muestra todas las acciones y plantillas generadas que se encuentran en la cache.

Listado 14-2 - Elementos de administración generados automáticamente, en cache/backend/ENV/modules/autoArticulo/

// Acciones en actions/actions.class.php
index            // Muestra un listado de todos los registros de la tabla
filter           // Actualiza los filtros que utiliza la acción list
new              // Muestra el formulario para crear un nuevo registro
create           // Crea un nuevo registro
edit             // Muestra un formulario para modificar la información de un registro
update           // Actualiza un registro existente
delete           // Borra un registro
batch            // Ejecuta una misma acción sobre todos los registros seleccionados
batchDelete      // Borra de una vez todos los registros seleccionados

// En 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

Los módulos de administración generados automáticamente se componen básicamente de tres vistas: list, new y edit. Si observas el código PHP, verás que es un código muy modular, fácil de leer y extensible.

14.2.3. Conceptos básicos del archivo de configuración generator.yml

Los módulos de administración generados se basan en las opciones del archivo de configuración generator.yml. Las opciones de configuración por defecto para un módulo de administración recién creado llamado articulo se pueden ver en el archivo backend/modules/articulo/config/generator.yml, reproducido en el listado 14-3.

Listado 14-3 - Configuración por defecto para la generación de la administración, en backend/modules/articulo/config/generator.yml

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

    config:
      actions: ~
      fields:  ~
      list:    ~
      filter:  ~
      form:    ~
      edit:    ~
      new:     ~

Esta configuración es suficiente para generar una administración básica. Todas las opciones propias se añaden bajo la clave config. El listado 14-4 muestra un archivo generator.yml típico.

Listado 14-4 - Configuración completa típica para el generador

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
    action_base_class:     sfActions

    config:
      actions:
        _new: { label: "Crear un nuevo articulo" }

      fields:
        autor_id:       { label: Autor del artículo }
        published_on:   { credentials: editor }

      list:
        title:          Artículos
        display:        [titulo, autor_id, category_id]
        fields:
          published_on: { date_format: dd/MM/yy }
        layout:         stacked
        params:         |
          %%publicado%%<strong>%%=title%%</strong><br /><em>by %%blog_autor%%
          in %%blog_categoria%% (%%created_at%%)</em><p>%%contenido%%</p>
        max_per_page:   2
        sort:           [titulo, asc]

      filter:
        display:        [title, blog_categoria_id, blog_autor_id, publicado]

      form:
        display:
          "Artículo":   [titulo, blog_categoria_id, contenido]
          "Gestión":    [blog_autor_id, publicado, created_at]
        fields:
          published_at: { help: "Fecha de publicación" }
          titulo:       { attributes: { style: "width: 350px" } }

      new:
        title:          Nuevo artículo

      edit:
        title:          Editando el artículo "%%titulo%%"

La configuración anterior se divide en seis secciones. Cuatro de estas secciones representan las vistas (list, filter, new y edit) y las otras dos secciones son virtuales (fields y form) ya que sólo se utilizan para tareas de configuración.

Las siguientes secciones explican en detalle todas las opciones que se pueden utilizar en este archivo de configuración.