Los formularios de Symfony 1.4

12.9. sfWidgetFormSchema

sfWidgetFormSchema es un tipo de widget especial compuesto por varios campos de formulario. Un campo es simplemente un widget asociado a un nombre:

$w = new sfWidgetFormSchema(array(
  'nombre' => new sfWidgetFormInput(),
  'pais'   => new sfWidgetFormI18nSelectCountry(),
));

Nota Los formularios se definen mediante un esquema de widgets de tipo sfWidgetFormSchema.

El constructor de sfWidgetFormSchema acepta cinco argumentos opcionales:

  • Un array de campos de formulario
  • Un array de opciones
  • Un array de atributos HTML
  • Un array de títulos para los widgets del esquema
  • Un array de mensajes de ayuda para los widgets del esquema

Las opciones disponibles son las siguientes:

Opción Descripción
name_format El formato que siguen los nombres de los campos (se debe utilizar la notación de sprintf y su valor por defecto es %s)
form_formatter El nombre del formato del formulario (Symfony incluye los formatos table y list, siendo table el que se utiliza por defecto)

Si quieres modificar el formato por defecto de todos los formularios, puedes utilizar el método setDefaultFormFormatterName():

sfWidgetFormSchema::setDefaultFormFormatterName('list');

Como sfWidgetFormSchema extiende la clase sfWidgetForm, hereda todos sus métodos y características.

Nota Los objetos sfWidgetFormSchema solamente muestran las filas que contienen los widgets y no la etiqueta que encierra a todos ellos (<table> en el formato de tablas y <ul> en el formato de listas):

<table>
  <?php echo $ws->render('') ?>
</table>

Se puede emplear sfWidgetFormSchema como si fuera un array para acceder a todos los widgets que incluye:

$ws = new sfWidgetFormSchema(array('nombre' => new sfWidgetFormInput()));

$widgetNombre = $ws['nombre'];

unset($ws['nombre']);

Nota Cuando un formulario incluye un esquema de widgets, el formulario te da acceso al campo asociado de la plantilla, pero no al propio widget, tal y como se explica en capítulos anteriores.

Los esquemas de widgets también se pueden anidar como cualquier otro tipo de widget:

$ws = new sfWidgetFormSchema(array(
  'titulo' => new sfWidgetFormInput(),
  'autor'  => new sfWidgetFormSchema(array(
    'nombre'     => new sfWidgetFormInput(),
    'apellidos'  => new sfWidgetFormInput(),
  )),
));

Para acceder a los esquemas de widgets anidados, se puede utilizar la notación de los arrays:

$ws['autor']['nombre']->setLabel('Nombre');

A continuación se describen los principales métodos de las clases de los esquemas de widgets. La documentación de la API de Symfony dispone de la lista completa de métodos y todas sus características.

12.9.1. Métodos setLabel(), getLabel(), setLabels() y getLabels()

Los métodos setLabel(), getLabel(), setLabels() y getLabels() controlan los títulos de los widgets incluidos en el esquema. En realidad, estos métodos son atajos de los métodos getLabel() y setLabel() de los widgets.

$ws = new sfWidgetFormSchema(array('nombre' => new sfWidgetFormInput()));

$ws->setLabel('nombre', 'Fabien');

// que es equivalente a...
$ws['nombre']->setLabel('Fabien');

// y también es equivalente a...
$ws->setLabel(array('nombre' => 'Fabien'));

El método setLabels() fusiona los valores indicados con los valores existentes.

12.9.2. Métodos setDefault(), getDefault(), setDefaults() y getDefaults()

Los métodos setDefault(), getDefault(), setDefaults() y getDefaults() controlan los valores por defecto de los widgets incluidos en el esquema. Estos métodos son atajos de los métodos getDefault() y setDefault() de los widgets.

$ws = new sfWidgetFormSchema(array('nombre' => new sfWidgetFormInput()));

$ws->setDefault('nombre', 'Fabien');

// que es equivalente a...
$ws['nombre']->setDefault('Fabien');

// y también es equivalente a...
$ws->setDefaults(array('nombre' => 'Fabien'));

El método setDefaults() fusiona los valores indicados con los valores existentes.

12.9.3. Métodos setHelp(), setHelps(), getHelps() y getHelp()

Los métodos setHelp(), setHelps(), getHelps() y getHelp() controlan los mensajes de ayuda asociados con los widgets incluidos en el esquema:

$ws = new sfWidgetFormSchema(array('nombre' => new sfWidgetFormInput()));

$ws->setHelp('nombre', 'Fabien');

// que es equivalente a...
$ws->setHelps(array('nombre' => 'Fabien'));

El método setHelps() fusiona los valores indicados con los valores existentes.

12.9.4. Métodos getPositions(), setPositions() y moveField()

Los campos que se incluyen en un esquema de widgets se encuentran ordenados. El orden se puede modificar con el método moveField():

$ws = new sfWidgetFormSchema(array(
  'nombre'    => new sfWidgetFormInput(),
  'apellidos' => new sfWidgetFormInput()
));

$ws->moveField('nombre', sfWidgetFormSchema::AFTER, 'apellidos');

Las constantes definidas para mover los widgets son las siguientes:

  • sfWidgetFormSchema::FIRST
  • sfWidgetFormSchema::LAST
  • sfWidgetFormSchema::BEFORE
  • sfWidgetFormSchema::AFTER

También se puede utilizar el método setPositions() para modificar todas las posiciones:

$ws->setPositions(array('apellidos', 'nombre'));

12.9.5. sfWidgetFormSchemaDecorator

sfWidgetFormSchemaDecorator es un tipo especial de esquema de widgets que permite decorar un esquema de widgets con el código HTML indicado.

$ws = new sfWidgetFormSchema(array('nombre' => new sfWidgetFormInput()));

$wd = new sfWidgetFormSchemaDecorator($ws, '<table>%content%</table>');

Nota Este widget lo utiliza Symfony internamente cuando un formulario se incluye dentro de otro formulario.