Ver índice de contenidos del libro

14.3. Configuración del generador

El archivo de configuración del generador es muy poderoso, ya que permite modificar la administración generada automáticamente de muchas formas. Lo único malo de que tenga tantas posibilidades es que la descripción completa de su sintaxis es muy larga de leer y cuesta aprenderla, por lo que este capítulo es uno de los más largos del libro. El sitio web de Symfony dispone de un recurso adicional para aprender más fácilmente su sintaxis: la chuleta del generador de la administración, que se puede ver en la figura 14-7 y que se puede descargar desde http://www.symfony-project.org/uploads/assets/sfAdminGeneratorRefCard.pdf. Puede ser de utilidad tener la chuleta a mano cuando se leen los ejemplos de este capítulo.

Los ejemplos de esta sección modifican el módulo de administración article y también el módulo commnent basado en la definición de la clase Comment. Antes de modificar el módulo comment, es necesario crear su ruta y después crear el módulo mediante la tarea propel:generate-admin:

comment:
  class: sfPropelRouteCollection
  options:
    model:               Comment
    module:              comment
    with_wildcard_routes: true
> php symfony propel:generate-admin backend comment
Chuleta del generador de administraciones

Figura 14.4 Chuleta del generador de administraciones

14.3.1. Campos

Por defecto, las columnas de la vista list son las columnas definidas en el archivo schema.yml. Los campos de las vistas new y edit son los que define el formulario asociado con el modelo (Articleform). El archivo generator.yml permite seleccionar los campos que se muestran y los que se ocultan. También permite añadir campos propios, incluso aunque no existan en el modelo de objetos.

14.3.2. Opciones de los campos

El generador de la administración crea un field para cada columna del archivo schema.yml. Bajo la clave fields se puede definir la forma en la que se muestra cada campo, su formato, etc. El ejemplo que se muestra en el listado 14-7 define un valor propio para el atributo class y un tipo de campo propio para title, además de un título y un mensaje de ayuda para el campo content. Las siguientes secciones describen en detalle cómo funciona cada opción.

Listado 14-7 - Establecer un título propio a cada columna

config:
  fields:
    title:
      label: Article Title
      attributes: { class: foo }
    content: { label: Body, help: Fill in the article body }

Además de las opciones globales para todas las vistas, se pueden redefinir las opciones de la clave fields para cada una de las vistas (list, filter, form, new y edit) tal y como muestra el listado 14-8.

Listado 14-8 - Redefiniendo las opciones globales en cada vista

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

  list:
    fields:
      title:   { label: Title }

  form:
    fields:
      content: { label: Body of the article }

Este ejemplo se puede tomar como una regla general: cualquier opción establecida para todo el módulo mediante la clave fields, se puede redefinir en la configuración de cualquier vista. A continuación se indican las normas que se siguen al redefinir las opciones:

  • new y edit heredan de form, que a su vez hereda de fields
  • list hereda de fields
  • filter hereda de fields

14.3.2.1. Mostrando nuevos campos

La sección fields permite definir para cada vista los campos que se muestran, los que se ocultan, la forma en la que se agrupan y las opciones para ordenarlos. Para ello se emplea la clave display. El código del listado 14-9 reordena los campos del módulo comment:

Listado 14-9 - Seleccionando los campos que se muestran, en modules/comment/config/generator.yml

config:
  fields:
    article_id: { label: Article }
    created_at: { label: Published on }
    content:    { label: Body }

  list:
    display:    [id, article_id, content]

  form:
    display:
      NONE:     [article_id]
      Editable: [author, content, created_at]

Con esta configuración, la vista list muetra tres columnas, como se ve en la figura 14-8 y el formulario de las vistas new y edit muestran cuatro campos agrupados en dos secciones, como se ve en la figura 14-9.

Columnas seleccionadas para la vista "list" del módulo "comment"

Figura 14.5 Columnas seleccionadas para la vista "list" del módulo "comment"

Agrupando campos en la vista "edit" del módulo "comment"

Figura 14.6 Agrupando campos en la vista "edit" del módulo "comment"

De esta forma, la opción display tiene dos propósitos:

  • En la vista list: crea un array simple con el nombre de los campos para seleccionar las columnas que se muestran y el orden en el que lo hacen.
  • En las vistas form, new y edit: crea un array asociativo cuya clave es el nombre del grupo o NONE si se quiere definir un grupo sin nombre. Las columnas también se indican mediante un array simple con los nombres de los campos en el mismo orden en el que se van a mostrar. Si no se incluyen todos los campos obligatorios referenciados en la clase del formulario, se producen errores de validación.

14.3.2.2. Campos propios

Los campos que se configuran en el archivo generator.yml ni siquiera tienen que corresponderse con alguna de las columnas definidas en el esquema. Si la clase relacionada incluye un método getter para el campo propio, este se puede utilizar como un campo más de la vista list; si además del getter existe un método setter, el campo también se puede utilizar en la vista edit. En el listado 14-10 se muestra un ejemplo que extiende el modelo de Article para añadir el método getNbComments() que obtiene el número de comentarios de un artículo.

Listado 14-10 - Añadiendo un getter propio en el modelo, en lib/model/Article.php

public function getNbComments()
{
  return $this->countComments();
}

Una vez definido este getter, el campo nb_comments está disponible como campo del módulo generado (el getter utiliza como nombre la habitual transformación camelCase del nombre del campo) como se muestra en el listado 14-11.

Listado 14-11 - Los getters propios permiten añadir más columnas a los módulos de administración, en backend/modules/article/config/generator.yml

config:
  list:
    display: [id, title, nb_comments, created_at]

La vista list resultante se muestra en la figura 14-10.

Campo propio en la vista "list" del módulo "article"

Figura 14.7 Campo propio en la vista "list" del módulo "article"

Los campos propios también pueden devolver código HTML para mostrarlo directamente. El listado 14-12 por ejemplo extiende la clase BlogComment con un método llamado getArticleLink() y que devuelve el enlace al artículo.

Listado 14-12 - Añadiendo un getter propio que devuelve código HTML, en lib/model/BlogComment.php

public function getArticleLink()
{
  return link_to($this->getBlogArticle()->getTitle(), 'article_edit', $this->getBlogArticle());
}

Este nuevo getter se puede utilizar como un campo propio en la vista comment/list utilizando la misma sintaxis que en el listado 14-11. El resultado se muestra en el listado 14-13 y se ilustra en la figura 14-11, en la que se puede ver el código HTML generado por el getter (un enlace al artículo) en la segunda columna sustituyendo a la clave primaria del artículo.

Listado 14-13 - Los getter propios que devuelven código HTML también se pueden utilizar como columnas, en modules/comment/config/generator.yml

config:
  list:
    display: [id, article_link, content]
Campo propio en la vista "list" del módulo "comment"

Figura 14.8 Campo propio en la vista "list" del módulo "comment"

14.3.2.3. Campos parciales

El código del modelo debe ser independiente de su presentación. El método getArticleLink() de ejemplo anterior no respeta el principio de la separación en capas, porque la capa del modelo incluye cierto código correspondiente a la vista. Para conseguir el mismo efecto pero manteniendo la separación de capas, es mejor incluir el código que genera el HTML del campo propio en un elemento parcial. Afortunadamente, el generador de la administración permite utilizar elementos parciales si la declaración del nombre del campo contiene un guión bajo como primer carácter. De esta forma, el archivo generator.yml del listado 14-13 debería modificarse para ser como el del listado 14-14.

Listado 14-14 - Se pueden utilizar elementos parciales como campos, mediante el uso del prefijo _

config:
  list:
    display: [id, _article_link, created_at]

Para que funcione la configuración anterior, es necesario crear un elemento parcial llamado _article_link.php en el directorio modules/comment/templates/, tal y como muestra el listado 14-15.

Listado 14-15 - Elemento parcial para la vista list del ejemplo, en modules/comment/templates/_article_link.php

<?php echo link_to($comment->getBlogArticle()->getTitle(), '@article_edit', $comment->getBlogArticle()) ?>

La plantilla de un elemento parcial tiene acceso al objeto actual mediante una variable que se llama igual que la clase ($comment en este ejemplo). Si se trabajara con un módulo construido para la clase llamada GrupoUsuario, el elemento parcial tiene acceso al objeto actual mendiante la variable $grupo_usuario.

El resultado de este ejemplo es idéntico al mostrado en la figura 14-11, salvo que en este caso se respeta la separación en capas. Si se acostumbra a separar el código en capas, el resultado será que las aplicaciones creadas son más fáciles de mantener.

Si se quieren definir los parámetros para un elemento parcial, se utiliza la misma sintaxis que para un campo normal. Bajo la clave field se indican los parámetros y en el nombre del campo no se debe incluir el guión bajo (_) inicial. El listado 14-16 muestra un ejemplo.

Listado 14-16 - Las propiedades de un elemento parcial se pueden definir bajo la clave fields

config:
  fields:
    article_link: { label: Article }

Si el código del elemento parcial crece demasiado, es recomendable sustituirlo por un componente. Para definir un campo basado en un componente, solamente es necesario reemplazar el perfijo _ por el prefijo ~, como muestra el listado 14-17.

Listado 14-17 - Se pueden utilizar componentes en los campos, mediante el prefijo ~

config:
  list:
    display: [id, ~article_link, created_at]

En la plantilla que se genera, la configuración anterior resulta en una llamada al componente articleLink del módulo actual.

Nota Los campos propios y los campos creados con elementos parciales se pueden utilizar en las vistas list, new, edit y filter. Si se utiliza el mismo elemento parcial en varias vistas, la variable $type almacena el contexto (list, new, edit o filter).

14.3.3. Modificando la vista

Si se quiere modificar el aspecto visual de las vistas new, edit y list, no se deben modificar las plantillas. Como se generan automáticamente, no es una buena idea modificarlas. En su lugar, se debe utilizar el archivo de configuración generator.yml, porque puede hacer prácticamente cualquier cosa que se necesite sin tener que sacrificar la modularidad de la aplicación.

14.3.3.1. Modificando el título de la vista

Además de una serie de campos propios, las páginas list, new y edit pueden mostrar un título específico. El listado 14-18 muestra cómo modificar el título de las vistas del módulo article. La vista edit resultante se ilustra en la figura 14-12.

Listado 14-18 - Estableciendo el título de cada vista, en backend/modules/article/config/generator.yml

config:
  list:
    title: List of Articles

  new:
    title: New Article

  edit:
    title: Edit Article %%title%% (%%id%%)
Título propio en la vista "edit" del módulo "article"

Figura 14.9 Título propio en la vista "edit" del módulo "article"

Como los títulos por defecto utilizan el nombre de cada clase, normalmente no es necesario modificarlos (siempre que el modelo utilice nombres de clase explícitos).

Truco En los valores de las opciones del archivo generator.yml, se puede acceder al valor de un campo mediante su nombre encerrado entre los caracteres %%.

14.3.3.2. Añadiendo mensajes de ayuda

En las vistas list, new y edit, se pueden añadir "tooltips" o mensajes de ayuda para describir los campos que se muestran en los formularios. El listado 14-19 muestra como añadir un mensaje de ayuda para el campo article_id en la vista edit del módulo comment. Para ello, se utiliza la propiedad help bajo la clave fields. El resultado se muestra en la figura 14-13.

Listado 14-19 - Añadiendo un mensaje de ayuda en la vista edit, en modules/comment/config/generator.yml

config:
  edit:
    fields:
      article_id: { help: The current comment relates to this article }
Mensaje de ayuda en la vista "edit" del módulo "comment"

Figura 14.10 Mensaje de ayuda en la vista "edit" del módulo "comment"

En la vista list, los mensajes de ayuda se muestran en la cabecera de la columna; en las vistas new, edit y filter, los mensajes se muestran debajo de cada cuadro de texto.

14.3.3.3. Modificando el formato de la fecha

Las fechas se pueden mostrar siguiendo un formato propio si se utiliza la opción date_format, tal y como se muestra en el listado 14-20.

Listado 14-20 - Dando formato a la fecha en la vista list

config:
  list:
    fields:
      created_at: { label: Published, date_format: dd/MM }

La sintaxis que se utiliza es la misma que la del helper format_date() descrito en el capítulo anterior.

14.3.4. Opciones específicas para la vista "list"

La vista list' puede mostrar la información de cada fila en varias columnas o de forma conjunta en una sola línea. También puede mostrar opciones para filtrar los resultados, paginación de resultados y opciones para odenar los datos. Todas estas opciones se pueden modificar mediante los archivos de configuración, como se muestra en las siguientes secciones.

14.3.4.1. Modificando el layout

Por defecto, la unión entre la vista list y la vista edit se realiza mediante la columna que muestra la clave primaria. Si se observa de nuevo la figura 14-11, se ve que la columna id de la lista de comentarios no solo muestra la clave primaria de cada comentario, sino que incluye un enlace que permite a los usuarios acceder de forma directa a la vista edit.

Si se quiere mostrar en otra columna el enlace a los datos detallados, se añade el prefijo = al nombre de la columna que se utiliza en la clave display. El listado 14-21 elimina la columna id de la vista list de los comentarios y establece el enlace en el campo content. La figura 14-14 muestra el resultado de este cambio.

Listado 14-21 - Cambiando el enlace a la vista edit en la vista list, en modules/comment/config/generator.yml

config:
  list:
    display:    [article_link, =content]
Estableciendo el enlace a la vista <code>edit</code> en otra columna, en la vista <code>list</code> del módulo <code>comment</code>

Figura 14.11 Estableciendo el enlace a la vista edit en otra columna, en la vista list del módulo comment

La vista list muestra por defecto todos sus datos en varias columnas. También es posible mostrar de forma seguida todos los datos en una sola cadena de texto que ocupe toda la anchura de la tabla. El aspecto con el que se muestran los datos se denomina "layout" y la forma en la que se muestran todos seguidos se denomina stacked. Si se utiliza el layout stacked, la clave params debe contener el patrón que define el orden en el que se muestran los datos. El listado 14-22 muestra por ejemplo el layout deseado para la vista list del módulo comment. La figura 14-15 ilustra el resultado final.

Listado 14-22 - Uso del layout stacked en la vista list, en modules/comment/config/generator.yml

config:
  list:
    layout:  stacked
    params:  |
      %%=content%%<br />
      (sent by %%author%% on %%created_at%% about %%article_link%%)
    display:  [created_at, author, content]
Layout "stacked" en la vista "list" del módulo "comment"

Figura 14.12 Layout "stacked" en la vista "list" del módulo "comment"

El layout normal en varias columnas requiere un array con el nombre de los campos en la clave display; sin embargo, el layout stacked requiere que la clave params incluya el código HTML que se utilizará para mostrar cada fila de datos. No obstante, el array de la clave display también se utiliza en el layout stacked para determinar las cabeceras de columnas disponibles para reordenar los datos mostrados.

14.3.4.2. Filtrando los resultados

En la vista de tipo list, se pueden añadir fácilmente una serie de filtros. Con estos filtros, los usuarios pueden mostrar menos resultados y pueden obtener más rápidamente los que están buscando. Los filtros se configuran mediante un array con los nombres de los campos en la clave filter. El listado 14-23 muestra como incluir un filtro según los campos article_id, author y created_at en la vista list del módulo comment, y la figura 14-16 ilustra el resultado. Para que el ejemplo funcione correctamente, es necesario añadir un método __toString() a la clase Article (este método puede devolver, por ejemplo, el valor title del artículo).

Listado 14-23 - Incluyendo filtros en la vista list, en modules/comment/config/generator.yml

config:
  list:
    layout:  stacked
    params:  |
      %%=content%% <br />
      (sent by %%author%% on %%created_at%% about %%article_link%%)
    display:  [created_at, author, content]

  filter:
    display: [article_id, author, created_at]
Filtros en la vista "list" del módulo "comment"

Figura 14.13 Filtros en la vista "list" del módulo "comment"

Los filtros que muestra Symfony dependen del tipo de columna definido en el esquema de datos y se pueden modificar en la clase de los filtros del formulario:

  • Para las columnas de texto (como el campo author en el módulo comment), el filtro es un cuadro de texto que permite realizar búsquedas textuales (los comodines se añaden automáticamente).
  • Para las claves externas (como el campo article_id en el módulo comment), el filtro es una lista desplegable con los datos de la columna correspondiente en la tabla asociada. Por defecto, las opciones de la lista desplegable son las que devuelve el método __toString() de la clase relacionada.
  • Para las fechas (como el campo created_at en el módulo comment), el filtro está formado por un par de elementos para seleccionar fechas, de forma que se pueda indicar un intervalo temporal.
  • Para las columnas booleanas, el filtro muestra una lista desplegable con los valores true, false y true or false (la última opción es para reinicializar el filtro).

Al igual que las vistas new y edit están relacionadas con la clase de un formulario, los filtros utilizan la clase del formulario de filtros asociado por defecto con el modelo (como por ejemplo ArticleFormFilter para el modelo Article). Si defines tu propia clase para el formulario de filtros, puedes personalizar los campos de los filtros aprovechando todas las opciones del framework de formularios y utilizando todos los widgets disponibles. Como muestra el listado 14-24, utilizar un filtro propio es tan sencillo como indicar la opción class dentro de la sección filter.

Listado 14-24 - Personalizando la clase del formulario utilizado para los filtros

config:
  filter:
    class: BackendArticleFormFilter

Truco Si quieres deshabilitar todos los filtros, utiliza false como valor de la opción class.

También puedes hacer uso de elementos parciales para modificar los filtros de Symfony. Cada elemento parcial recibe como argumentos form y attributes que se utilizan para mostrar el elemento del formulario. El listado 14-24 muestra un ejemplo que utiliza elementos parciales para obtener el mismo comportamiento que el de por defecto.

Listado 14-24 - Utilizando un elemento parcial como filtro

// El elemento parcial se define en templates/_state.php
<?php echo $form[$name]->render($attributes->getRawValue()) ?>
// Se añade el filtro parcial en la lista de filtros de config/generator.yml
config:
  filter: [date, _state]

14.3.4.3. Ordenando el listado

Como muestra la figura 14-18, en la vista list las columnas que forman la cabecera de la tabla son enlaces que se pueden utilizar para reordenar los datos del listado. Las cabeceras se muestran tanto en el layout normal como en el layout stacked. Al pinchar en cualquiera de estos enlaces, se recarga la página añadiendo un parámetro sort que permite reordenar los datos de forma adecuada.

Las cabeceras de la tabla de la vista "list" permiten reordenar los datos

Figura 14.14 Las cabeceras de la tabla de la vista "list" permiten reordenar los datos

Se puede utilizar la misma sintaxis que emplea Symfony para incluir un enlace que apunte directamente a los datos ordenados de una forma determinada:

<?php echo link_to('Listado de comentarios ordenados por fecha', '@comments?sort=created_at&sort_type=desc' ) ?>

También es posible indicar en el archivo generator.yml el orden por defecto para la vista list mediante el parámetro sort. El listado 14-26 muestra un ejemplo de la sintaxis que debe utilizarse.

Listado 14-26 - Estableciendo un orden por defecto en la vista list

config:
  list:
    sort:   created_at
    # Sintaxis alternativa para indicar la forma de ordenar
    sort:   [created_at, desc]

Nota Solamente se pueden reordenar los datos mediante los campos que se corresponden con columnas reales, no mediante los campos propios y los campos parciales.

14.3.4.4. Modificando la paginación

La administración generada automáticamente tiene en cuenta la posibilidad de que las tablas contengan muchos datos, por lo que la vista list incluye por defecto una paginación de datos. Si el número total de filas de la tabla es mayor que el número máximo de filas por página, entonces aparece la paginación al final del listado. La figura 14-19 muestra el ejemplo de un listado con 6 comentarios de prueba para el que el número máximo de comentarios por página es de 5. La paginación de datos asegura un buen rendimiento a la aplicación, porque solamente se obtienen los datos de las filas que se muestran, y permite una buena usabilidad, ya que hasta las filas que contienen millones de filas se pueden manejar con el módulo de administración.

La paginación se muestra cuando el listado es muy largo

Figura 14.15 La paginación se muestra cuando el listado es muy largo

El número máximo de filas que se muestran en cada página se controla mediante la opción max_per_page:

config:
  list:
    max_per_page:   5

14.3.4.5. Mejorando el rendimiento mediante una Join

El generador de la administración utiliza por defecto el método doSelect() para obtener las filas de datos. Sin embargo, si se utilizan objetos relacionados en el listado, el número de consultas a la base de datos puede aumentar demasiado. Si se quiere mostrar por ejemplo el nombre del artículo en el listado de comentarios, se debe hacer una consulta adicional por cada comentario para obtener el objeto Article relacionado. Afortunadamente, se puede indicar al paginador que utilice un método específico tipo doSelectJoinXXX() para optimizar el número de consultas necesario. La opción peer_method es la encargada de indicar el método a utilizar.

config:
  list:
    peer_method: doSelectJoinArticle

En el Capítulo 18 se explica más detalladamente el concepto de Join.

14.3.5. Opciones específicas para las vistas new y edit

Las vistas new y edit permiten al usuario modificar el valor de cualquier columna de un registro nuevo o existente de la base de datos. Por defecto, el formulario utilizado por el generador de la parte de administración es el formulario asociado con el modelo: BlogArticleForm para el modelo BlogArticle. Si quieres utilizar una clase propia, puedes indicarlo en la opción class de la sección form, tal y como muestra el listado 14-27.

Listado 14-27 - Utilizando una clase de formulario propia en las vistas new y edit

config:
  form:
    class: BackendBlogArticleForm

Si se emplea una clase de formulario propia, es posible modificar todos los widgets y validadores utilizados por el generador de la parte de administración. Además, en este caso la clase de formulario por defecto se puede utilizar y modificar para su uso específico en la aplicación frontend.

El listado 14-28 muestra cómo personalizar los títulos, mensajes de ayuda y layout del formulario directamente desde el archivo de configuración generator.yml.

Listado 14-28 - Modificando el aspecto del formulario

config:
  form:
    display:
      NONE:     [article_id]
      Editable: [author, content, created_at]
    fields:
      content:  { label: body, help: "The content can be in the Markdown format" }

14.3.5.1. Manejando los campos parciales

Las vistas new y edit pueden utilizar los mismos elementos parciales que se emplean en las vistas de tipo list.

14.3.6. Trabajando con claves externas

Si el esquema de la aplicación define relaciones entre tablas, los módulos generados para la administración pueden aprovechar esas relaciones para automatizar aun más los campos, simplificando enormemente la gestión de las relaciones entre tablas.

14.3.6.1. Relaciones uno-a-muchos

El generador de la administración se ocupa automáticamente de las relaciones de tipo 1-n entre tablas. Como se muestra en la figura 14-1, la tabla blog_comment se relaciona con la tabla blog_article mediante el campo article_id. Si se utiliza el generador de administraciones para iniciar el módulo de la clase BlogComment, la acción edit muestra automáticamente el campo article_id como una lista desplegable con los valores de los ID de todas las filas de datos de la tabla blog_article (la figura 14-9 también muestra una figura de esta relación).

Además, si se define un método __toString() en la clase Article, la lista desplegable puede mostrar otro texto para cada opción en vez del valor de la clave primaria de la fila.

Si se quiere mostrar la lista de comentarios relacionados con un artículo en el módulo article (relación 1-n) se debe modificar el módulo y utilizar un campo parcial.

14.3.6.2. Relaciones muchos-a-muchos

Symfony también se encarga de las relaciones n-n, como se muestra en la figura 14-20.

Uso de una tabla intermedia en las relaciones muchos-a-muchos

Figura 14.16 Uso de una tabla intermedia en las relaciones muchos-a-muchos

Personalizando el widget utilizado para mostrar este tipo de relación, se puede modificar la forma en la que se muestra el widget (ver figura 14-21):

Tipos de campos especiales disponibles para la gestión de las relaciones muchos-a-muchos

Figura 14.17 Tipos de campos especiales disponibles para la gestión de las relaciones muchos-a-muchos

14.3.7. Añadiendo nuevas interacciones

Los módulos de administración permiten a los usuarios realizar las operaciones CRUD habituales, aunque también es posible añadir otras interacciones diferentes o restringir las interacciones disponibles en una vista. La configuración que se muestra en el listado 14-31 habilita todas las operaciones CRUD habituales para el módulo article.

Listado 14-31 - Definiendo las interacciones de cada vista, en backend/modules/article/config/generator.yml

config:
  list:
    title:          List of Articles
    object_actions:
      _edit:         ~
      _delete:       ~
    batch_actions:
      _delete:       ~
    actions:
      _new:          ~

  edit:
    title:          Body of article %%title%%
    actions:
      _delete:       ~
      _list:         ~
      _save:         ~
      _save_and_add: ~

En la vista de tipo list, existen tres opciones relacionadas con las acciones: la lista de las acciones disponibles para todos los objetos (object_actions), la lista de opciones disponibles para una selección de objetos (batch_actions) y la lista de acciones disponibles para la página entera (actions). La lista de interacciones definidas en el listado 14-31 producen el resultado de la figura 14-22. Cada fila de datos muestra un botón para modificar la información y un botón para eliminar ese registro, además de un checkbox en cada fila para poder borrar varios elementos seleccionados. Al final de la lista se muestra un botón para crear nuevos elementos.

Interacciones de la vista "list"

Figura 14.18 Interacciones de la vista "list"

En las vistas new y edit, como sólo se modifica un registro de datos cada vez, solamente se define un conjunto de acciones (en actions). Las interacciones definidas en el listado 14-31 se muestran con el aspecto de la figura 14-23. Tanto la acción save (guardar) como la acción save_and_add (guardar_y_añadir) guardan los cambios realizados en los datos. La única diferencia es que la acción save vuelve a mostrar la vista edit con los nuevos datos y la acción save_and_add muestra la vista new para añadir otro elemento. Por tanto, la acción save_and_add es un atajo muy útil cuando se están añadiendo varios elementos de forma consecutiva. El botón de la acción delete (borrar) se encuentra lo suficientemente alejado de los otros dos botones como para que no sea pulsado por accidente.

Los nombres de las interacciones que empiezan con un guión bajo (_) son reconocidos por Symfony y por tanto, utilizan el mismo icono y realizan la misma acción que las interacciones por defecto. El generador de la administración es capaz de reconocer las acciones _edit, _delete, _new, _list, _save, _save_and_add y _create.

Interacciones de la vista "edit"

Figura 14.19 Interacciones de la vista "edit"

También es posible definir interacciones propias, para lo que se debe especificar un nombre que no empiece por guión bajo y una acción del módulo actual, tal y como se muestra en el listado 14-32.

Listado 14-32 - Definiendo una interacción propia

list:
  title:          List of Articles
  object_actions:
    _edit:        -
    _delete:      -
    addcomment:   { label: Add a comment, action: addComment }

Ahora, cada artículo que aparece en el listado muestra un enlace con el texto Add a comment, tal y como se muestra en la figura 14-24. Al pinchar sobre ese enlace, se ejecuta la acción addComment del módulo actual. La clave primaria del objeto relacionado se pasa automáticamente a los parámetros de la petición que se produce.

Interacciones propias en la vista "list"

Figura 14.20 Interacciones propias en la vista "list"

La acción addComment puede ser tan sencilla como la que muestra el listado 14-33.

Listado 14-33 - Acción para una interacción propia, en actions/actions.class.php

public function executeAddComment($peticion)
{
  $comment = new Comment();
  $comment->setArticleId($peticion->getParameter('id'));
  $comment->save();
 
  $this->redirect('comments_edit', $comment);
}

Las acciones de tipo batch reciben un array con todas las claves primarias de las filas seleccionadas mediante el parámetro sf_admin_batch_selection de la petición.

Por último, si se quieren eliminar todas las acciones para una determinada vista, se utiliza una lista vacía como la del listado 14-34.

Listado 14-34 - Eliminando todas las acciones en la vista list

config:
  list:
    title:   List of Articles
    actions: {}

14.3.8. Validación de formularios

La validación de datos se realiza de forma automática en el formulario utilizado en las vistas new y edit. Si se quiere personalizar la validación, se deben modificar las clases correspondientes de cada formulario.

14.3.9. Restringiendo las acciones del usuario mediante credenciales

Los campos y las interacciones disponibles en un módulo de administración pueden variar en función de las credenciales del usuario conectado (el Capítulo 6 describe las opciones de seguridad de Symfony).

Los campos definidos en el generador pueden incluir una opción credentials para restringir su acceso solamente a los usuarios con la credencial adecuada. Esta característica se puede utilizar en la vista list. Además, el generador puede ocultar algunas interacciones en función de la credenciales del usuario. El listado 14-37 muestra estas opciones.

Listado 14-37 - Utilizando credenciales en generator.yml

config:
  # La columna id solamente se muestra para los usuarios con la credencial "admin"
  list:
    title:          List of Articles
    display:        [id, =title, content, nb_comments]
    fields:
      id:           { credentials: [admin] }
 
  # La interacción "addcomment" se restringe a los usuarios con la credencial "admin"
  actions:
    addcomment: { credentials: [admin] }