Symfony 1.2: El Generador Admin

Hoy, hemos fusionado la rama new_admin dentro de 1.2, lo que significa que symfony 1.2 ahora juega con el nuevo generador de admin, basado en el framework de formularios.

En este artículo, Sólo voy a describir los conceptos generales del nuevo generador de admin.
El capítulo sobre el generador de admin
en el libro symfony ya se ha actualizado, de modo que puedes comenzar a leerlo de inmediato.

La primera buena noticia es que el nuevo generador de admin es muy similar al anterior. Incluso siendo que no es muy compatible hacia atrás en el sentido de que utiliza el nuevo framework de formularios, la configuración sigue siendo manejada por el archivo de configuración generator.yml, y las posibilidades de configuración son bastante similares.
También he tratado de mantener la misma filosofía para ayudar a los usuarios actuales a aprender la nueva herramienta con más facilidad.

Un simple CMS como ejemplo

Para ilustrar este artículo, Tomemos el ejemplo que ya hemos utilizado en un artículo anterior:

propel:
  demo_article:
    id:             ~
    author_id:      { type: integer, foreignReference: id, foreignTable: demo_author, onDelete: cascade, onUpdate: cascade, required: true }
    status:         { type: varchar(255), required: true }
    title:          { type: varchar(255), required: true }
    content:        { type: longvarchar, required: true }
    is_on_homepage: boolean
    published_at:   timestamp
    created_at:     timestamp
    updated_at:     timestamp
 
  demo_category:
    id:          ~
    name:        varchar(255)
 
  demo_author:
    id:          ~
    name:        varchar(255)
 
  demo_tag:
    id:          ~
    name:        varchar(255)
 
  demo_tag_article:
    tag_id:      { type: integer, primaryKey: true, foreignReference: id, foreignTable: demo_tag, onDelete: cascade, onUpdate: cascade, required: true }
    article_id:  { type: integer, primaryKey: true, foreignReference: id, foreignTable: demo_article, onDelete: cascade, onUpdate: cascade, required: true }
 
  demo_category_article:
    category_id: { type: integer, primaryKey: true, foreignReference: id, foreignTable: demo_category, onDelete: cascade, onUpdate: cascade, required: true }
    article_id:  { type: integer, primaryKey: true, foreignReference: id, foreignTable: demo_article, onDelete: cascade, onUpdate: cascade, required: true }
 

Este es un esquema clásico de un simple CMS. Los artículos tienen un autor y puede tener muchas etiquetas y categorías.

Una arquitectura REST

El nuevo administrador generador se basa en una arquitectura REST. Esto significa que usted necesitas crear una colección de rutas REST para el nuevo modulo admin. Aquí hay un ejemplo para el modelo DemoArticle con todas las opciones necesarias:

# apps/frontend/config/routing.yml
articles:
  class:   sfPropelRouteCollection
  options:
    model:       DemoArticle
    module:      article
    with_show:   false
    collection_actions: { filter: post, batch: post }
 

La anterior ruta genera las siguientes rutas:

route name	method	pattern
articles_filter	POST	/articles/filter.:sf_format
articles_batch	POST	/articles/batch.:sf_format
articles	GET	/articles.:sf_format
articles_new	GET	/articles/new.:sf_format
articles_create	POST	/articles.:sf_format
articles_edit	GET	/articles/:id/edit.:sf_format
articles_update	PUT	/articles/:id.:sf_format
articles_delete	DELETE	/articles/:id.:sf_format
articles_show	GET	/articles/:id.:sf_format

Sobre la base de esta definición de ruta, symfony es capaz de generar el correspondiente módulo de admin:

$ php symfony propel:generate-admin backend articles

La tarea propel:generate-admin crea un modulo article en la aplicacion backend y dentro del directorio modules.

Podemos hacer lo mismo para generar un módulo para el modelo DemoCategory:

categories:
  class:   sfPropelRouteCollection
  options:
    model:       DemoCategory
    module:      category
    with_show:   false
    collection_actions: { filter: post, batch: post }
 

$ php symfony propel:generate-admin backend categories

Mas de Fabrica

Incluso antes de la configuración de los módulos generados, Vamos a echar un vistazo a las características que están disponibles desde fabrica/caja (significa antes de cualquier personalización).

La lista Category tiene varias características interesantes:

• Cada categoría id es un enlace a la vista edit
• El enlace ‘New’ va a la vista new para crear un nueva categoría
• Cada categoría tiene un enlace ‘Edit’ y uno ‘Delete’
• La posibilidad de suprimir categorías seleccionando de varias categorías a la vez

La captura de pantalla anterior es el filtro por defecto creado para el modelo Article. Observe que el nuevo generador de admin ha creado automáticamente filtros para las foreign-keys y las relaciones muchos a muchos.

La vista edit también es muy interesante ya que todos los campos son editables, incluso las relaciones muchos a muchos entre los modelos Article, Tag y Category.

En esta vista usa la clase form por defecto generada por la clase Article, la validación también esta activada por defecto:

Para una mejor usabilidad para el usuario final, el nuevo generador de admin también utiliza un montón de mensajes flash en las vistas list y edit:

Más configurable

De fabrica, los módulos generados ya son muy potente, pero el poder real del generador de admin siempre ha sido su configurabilidad, la forma en que puedes cambiar la pantalla del admin sin escribir una sola línea de código. El nuevo generador de admin no es diferente. Veamos algunas opciones que puedes usar en el archivo de configuración generator.yml.

En primer lugar, el archivo generator.yml es más seguro que antes symfony ahora valida el formato del archivo. Se le ahorrará un montón de tiempo en el caso de un error o un mal sangrado. Para que esta validación funcione, hemos pasado toda la configuración bajo la entrada de config. Aquí está el archivo de configuración por defecto generator.yml para el modulo category:

generator:
  class: sfPropelGenerator
  param:
    model_class:           DemoCategory
    theme:                 admin
    non_verbose_templates: true
    with_show:             false
    singular:              ~
    plural:                ~
    route_prefix:          categories
    with_propel_route:     1
 
    config:
      actions: ~
      fields:  ~
      list:    ~
      filter:  ~
      form:    ~
      edit:    ~
      new:     ~
 

Debes haber notado el new. El nuevo generador implementa una de la características más solicitada, la posibilidad de tener una configuración diferente para la vista edit y la new. Sí, eso es ahora posible, y ambas opiniones heredan de una vista virtual form:

config:
  form:
    display:
      NONE:    [author_id, status, published_at, demo_category_article_list, demo_tag_article_list]
      Content: [title, content, is_on_homepage]
 
  new:
    title: New Article
 
  edit:
    title: Editing Article %%title%% (#%%id%%)
 

Por lo tanto, el generador de admin tiene ahora siete principales entradas:

• actions: Para definir los atributos de todas las acciones, y, en particular, las credenciales
• fields: Para definir los campos de configuración por defecto
• list: Para definir la configuración de la vista lista
• filter: El filtro tiene ahora su propia entrada para su configuración
• form: Esta es una vista virtual ya que sólo se utiliza como la configuración por omisión para las configuraciones de new y edit
• new: Para definir la configuración de vista new
• edit: Para definir la configuración de vista edit

El archivo de configuración generator.yml implementa algunas reglas de herencia entre estas entradas:

• new and edit heredan de form la cual hereda de fields
• list heredan de fields
• filter heredan de fields

Aquí hay un ejemplo para la definición de campos:

config:
  fields:
    title:     { label: Article Title }
    content:   { label: Body }
 

  list:
    fields:
      title:   { label: Title }
 
  form:
    fields:
      content: { label: Body of the article }
 

Si utilizas el generador de admin de symfony 1.0, te darás cuenta de que la clave name ha sido renombrada a label.

Todas las características del viejo archivo de configuración están aun soportadas (mira el Capítulo 14 para más detalles).

También, incluso si el archivo de configuración generator.yml es el método recomendado para personalizar los módulos, el nuevo generador de admin también puede ser totalmente personalizado con código PHP para una configuración más dinámica, (apps/backend/modules/article/lib/articleGeneratorConfiguration.class.php). Para tener una idea de lo que es posible, sólo echa un vistazo a la clase generada BaseArticleGeneratorConfiguration en el cache (cache/backend/dev/modules/autoArticle/lib/BaseArticleGeneratorConfiguration.class.php). Puedes incluso mezclar configuración via el archivo generator.yml y la clase articleGeneratorConfiguration.

Extensibilidad

El nuevo generador de admin realmente brilla cuando se trata de ampliar el comportamiento por defecto. Es mucho más flexible y extensible que antes.

Primero, hay más plantillas parciales que antes, y cada parcial es mucho más simple, lo que te permite afinar cada parte del sistema fácilmente:

_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

La plantilla para la acción se ha dividido en un montón de parciales para una mejor legibilidad y extensibilidad:

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

Si desea modificar el admin generador para crear su propio tema, o para empaquetar tus extensiones en un plugin, encontrarás que es mucho más fácil ahora:

• No es necesario copiar todos los archivos del tema por defecto para crear una nuevo. Sólo tienes que copiar los ficheros que necesita para sobreescribir.
• Varios eventos se han añadido para agregar comportamientos sin la necesidad de crear un nuevo tema. Esto permite que varios plug-ins puedan agregar o cambiar el comportamiento por defecto:
  • admin.pre_execute: Este evento es notificado antes de cualquier acción sea ejecutada. Este es un gran lugar para modificar la configuración o comprobar algo antes de que algo sea ejecutado.
  • admin.build_criteria: Este evento filtra el Criteria usado por la vista list.
  • admin.save_object: Este evento es notificado inmediatamente después de que un objeto sea guardado.
  • admin.delete_object: Este evento es notificado justo antes de un objeto se eliminado.
• El módulo generadod de acciones ha sido refactoreado para dar métodos más útiles:
  • getFilters()
  • setFilters()
  • getPager()
  • getPage()
  • setPage()
  • buildCriteria()
  • addSortCriteria()
  • getSort()
  • setSort()

La mejor manera de aprender cómo se puede empujar los límites del nuevo generador de admin es examinar los módulos generados en la memoria caché. Encontrarás una gran cantidad de la bondades (¡Echa un vistazo a la clase helper por ejemplo).

Internacionalización

El nuevo generador de admin soporta internacionalización de formularios de forma nativa (de fabrica), gracias a la utilización del nuevo framework de formularios.

La interface del generador de adminis también esta traducida en varios idiomas. En menos de 24 horas, ya tenemos traducciones para 21 idiomas:

• English
• Bulgarian
• German
• Danish
• Spanish
• Spanish (Argentina)
• French
• Italian
• Japanese
• Dutch
• Novergian
• Polish
• Brasilian
• Russian
• Chinese simplified
• Slovak
• Romanian
• Indonesian
• Turkish
• Finnish
• Portuguese

Si deseas contribuir con una traducción de tu idioma, el proceso es muy fácil y te llevará unos 10 minutos:

• Descarga el archivo en Frances y sustituye todas las cadenas del francés con tus traducciones (el archivo contiene también la cadenas de Inglés)
• Cambie el nombre del archivo con tu código ISO de idioma
• Enviar el archivo traducido a mi dirección de correo electrónico

Aprovecha el nuevo framework de formularios

Las vistas filters, new, y edit son generadas por el nuevo framework de formularios, lo que significa que puedes aprovechar todas las características del nuevo framework de formularios para modificar tus módulos de admin generados.

Esto fue una muy rápida descripción general y técnica del nuevo generador de admin. Si deseas aprender más, puedes leer el capítulo generador del libro de symfony.

La presente, es una traducción al castellano realizada por Roberto G. Puentes Diaz,
sobre el artículo new-in-symfony-1-2-the-admin-generator de Fabien Potencier.