Capítulo 12. Referencia de Widgets (Los formularios de Symfony 1.4)

12.1. Introducción

El framework de formularios de Symfony incluye muchos widgets útiles que cubren las necesidades más comunes de la mayoría de proyectos. En este capítulo se describen detalladamente todos los widgets que incluye por defecto Symfony. También se explican los widgets incluidos en los plugins sfFormExtraPlugin, sfPropelPlugin y sfDoctrinePlugin, ya que estos plugins los desarrollan los creadores de Symfony e incluyen muchos widgets útiles.

Nota Aunque no utilices el framework Symfony, puedes hacer uso de los widgets incluidos en sfFormExtraPlugin, sfPropelPlugin y sfDoctrinePlugin simplemente copiando el directorio widget/ de cada plugin en algún lugar de tu proyecto.

Antes de profundizar en los detalles de cada widget, veamos las características comunes de todos los widgets.

12.1.1. La clase base sfWidget

Todos los widgets de Symfony heredan de la clase base sfWidget, que proporciona las características comunes de todos los widgets.

Los widgets se muestran por defecto mediante XHTML, aunque se puede cambiar a HTML con el método setXhtml():

sfWidget::setXhtml(false);

Los widgets también se encargan de aplicar de forma automática el mecanismo de escape a los atributos HTML y a todos los contenidos potencialmente peligrosos. Para ello, es necesario conocer la codificación utilizada en el proyecto. Por defecto la codificación utilizada es UTF-8, pero se puede configurar cualquier otra codificación mediante el método setCharset():

sfWidget::setCharset('ISO-8859-1');

Nota Si utilizas los widgets de Symfony dentro de un proyecto Symfony, la codificación se obtiene directamente a partir de su valor en el archivo de configuración settings.yml.

Si un widget necesita hojas de estilos y/o archivos de JavaScript para funcionar, también se pueden redefinir los métodos getJavaScripts() y getStylesheets():

class Widget extends sfWidget
{
  public function getStylesheets()
  {
    // las claves de los arrays son las rutas de los archivos y los
    // valores son los nombres de los medios CSS separados por comas
    return array(
      '/ruta/hasta/archivo.css' => 'all',
      '/otro/archivo.css' => 'screen,print',
    );
  }

  public function getJavaScripts()
  {
    return array('/ruta/hasta/archivo.js', '/otro/archivo.js');
  }
}

12.1.2. La clase base sfWidgetForm

En esta sección se van a mostrar los widgets de formulario. Todos ellos heredan de la clase base sfWidgetForm, que a su vez extiende la clase sfWidget para proporcionar algunas características útiles por defecto.

Cuando se crea un widget, se le pueden pasar como argumentos opcionales diferentes opciones y atributos HTML:

$w = new sfWidgetFormInput(
  array('default' => 'Fabien'),
  array('class' => 'foo')
);

Las opciones y los atributos HTML también se pueden establecer con los métodos setOptions() y setAttributes():

$w = new sfWidgetFormInput();
$w->setOptions(array('default' => 'Fabien'));
$w->setAttributes(array('class' => 'foo'));

Si se quiere establecer una opción o atributo HTML individual, se pueden utilizar los métodos setOption() y setAttribute():

$w = new sfWidgetFormInput();
$w->setOption('default', 'Fabien');
$w->setAttribute('class', 'foo');

Los widgets se muestran invocando el método render():

$w->render('nombre', 'valor', array('class' => 'foo'));

El método render() acepta los siguientes argumentos:

El nombre del widget
El valor del widget
Atributos HTML opcionales (estos atributos se unen a los atributos por defecto establecidos al construir el widget)

Nota Los widgets no almacenan información sobre su estado, lo que significa que una sola instancia del widget se puede mostrar tantas veces como necesites con diferentes argumentos.

El widget anterior se muestra de la siguiente forma:

<input class="foo" type="text" name="nombre" id="nombre" />

sfWidgetForm define las siguientes opciones por defecto:

Opción	Descripción
`is_hidden`	Vale `true` si el widget debe ser de tipo oculto y `false` en cualquier otro caso (su valor por defecto es `false`)
`needs_multipart`	Vale `true` si el widget requiere que el formulario sea de tipo multipart (por ejemplo para adjuntar archivos) y `false` en cualquier otro caso (su valor por defecto es `false`)
`default`	El valor inicial que debe mostrar el widget
`label`	El título que se debe utilizar cuando se muestra el widget mediante un esquema de widgets
`id_format`	El formato utilizado para generar los atributos `id` de HTML (su valor por defecto es `%s`)

Nota La opción is_hidden la utilizan las clases del esquema de widgets para mostrar los widgets ocultos sin ninguna decoración. La opción needs_multipart la utilizan las clases de formulario para añadir el atributo enctype="multipart/form-data" cuando se muestra una etiqueta <form>.

La clase sfWidgetForm también incluye métodos accesores para todas las opciones:

is_hidden: métodos isHidden() y setHidden()
needs_multipart: método needsMultipartForm()
default: métodos getValue() y setValue()
label: métodos getLabel() y setLabel()
id_format: métodos getIdFormat() y setIdFormat()

12.1.3. Esquema de widgets

Un esquema de widgets de formulario es un widget especial que agrupa uno o varios widgets.

En las siguientes secciones, los widgets se han agrupado en categorías para facilitar su explicación.