Un campo multipropósito para que el usuario pueda «elegir» una o más opciones. Este se puede representar como una etiqueta select, botones de radio o casillas de verificación.
Para utilizar este campo, debes especificar algún elemento de la choice_list o choices.
| Rendered as | can be various tags (see below) |
| Options | |
| Inherited options | |
| Parent type | form (if expanded), field otherwise |
| Class | Symfony\Component\Form\Extension\Core\Type\ChoiceType |
La forma fácil de utilizar este campo es especificando las opciones directamente a través de la opción choices. La clave del arreglo se convierte en el valor que en realidad estableces en el objeto subyacente (por ejemplo, m), mientras que el valor es lo que el usuario ve en el formulario (por ejemplo, Hombre).
$builder->add('gender', 'choice', array(
'choices' => array('m' => 'Male', 'f' => 'Female'),
'required' => false,
));
Al establecer multiple a true, puedes permitir al usuario elegir varios valores. El elemento gráfico se reproduce como una etiqueta select múltiple o una serie de casillas de verificación dependiendo de la opción expanded:
$builder->add('availability', 'choice', array(
'choices' => array(
'morning' => 'Morning',
'afternoon' => 'Afternoon',
'evening' => 'Evening',
),
'multiple' => true,
));
También puedes utilizar la opción choice_list, la cual toma un objeto que puede especificar las opciones para el elemento gráfico.
Este campo se puede reproducir como uno de varios campos HTML, dependiendo de las opciones expanded y multiple:
| tipo elemento | expandido | múltiple |
|---|---|---|
| etiqueta de selección | false | false |
| etiqueta de selección (con atributo multiple) | false | true |
| botones de radio | true | false |
| caja de verificación (checkboxes) | true | true |
tipo: array predeterminado: array()
Esta es la forma más sencilla de especificar las opciones que debe utilizar este campo. La opción choices es un arreglo, donde la clave del arreglo es el valor del elemento y el valor del arreglo es la etiqueta del elemento:
$builder->add('gender', 'choice', array(
'choices' => array('m' => 'Male', 'f' => 'Female')
));
tipo: Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface
Esta es una manera de especificar las opciones que se utilizan para este campo. La opción choice_list debe ser una instancia de ChoiceListInterface. Para casos más avanzados, puedes crear una clase personalizada que implemente la interfaz para suplir las opciones.
tipo: Boolean predeterminado: false
Si es true, el usuario podrá seleccionar varias opciones (en contraposición a elegir sólo una opción). Dependiendo del valor de la opción expanded, esto reproducirá una etiqueta de selección o casillas de verificación si es true y una etiqueta de selección o botones de radio si es false. El valor devuelto será un arreglo.
tipo: Boolean predeterminado: false
Si es true, los botones de radio o casillas de verificación se reproducirán (en función del valor de multiple). Si es false, se reproducirá un elemento de selección.
tipo: array predeterminado: array()
Si se especifica esta opción, entonces un subconjunto de todas las opciones se trasladará a la parte superior del menú de selección. Lo siguiente debe mover la opción «Baz» a la parte superior, con una separación visual entre esta y el resto de las opciones:
$builder->add('foo_choices', 'choice', array(
'choices' => array('foo' => 'Foo', 'bar' => 'Bar', 'baz' => 'Baz'),
'preferred_choices' => array('baz'),
));
Ten en cuenta que las opciones preferidas sólo son útiles cuando se reproducen como un elemento select (es decir, expanded es false). Las opciones preferidas y las opciones normales están separadas visualmente por un conjunto de líneas punteadas (es decir, -------------------). Esto se puede personalizar cuando reproduzcas el campo:
{{ form_widget(form.foo_choices, { 'separator': '=====' }) }}
<?php echo $view['form']->widget($form['foo_choices'], array('separator' => '=====')) ?>
tipo: string o Boolean
Esta opción determina si o no una opción empty especial (por ejemplo, «Elige una opción») aparecerá en la parte superior de un elemento gráfico de selección. Esta opción sólo se aplica si ambas opciones expanded y multiple se establecen en false.
Añade un valor vacío con «Elige una opción», como el texto:
$builder->add('states', 'choice', array(
'empty_value' => 'Choose an option',
));
Garantiza que ninguna opción con valor empty se muestre:
$builder->add('states', 'choice', array(
'empty_value' => false,
));
Si dejas sin establecer la opción empty_value, entonces automáticamente se añadirá una opción con espacio en blanco (sin texto) si y sólo si la opción required es false:
// añadirá una opción de espacio en blanco (sin texto)
$builder->add('states', 'choice', array(
'required' => false,
));
tipo: mixed predeterminado: array() si multiple o expanded, de lo contrario ''
Esta opción determina qué valor devolverá el campo cuando está seleccionada la opción empty_value.
Por ejemplo, si deseas que el campo género que, cuando no hay valor seleccionado, se configure en null, lo puedes hacer de la siguiente manera:
$builder->add('gender', 'choice', array(
'choices' => array(
'm' => 'Male',
'f' => 'Female'
),
'required' => false,
'empty_value' => 'Choose your gender',
'empty_data' => null
));
Nota
If you want to set the empty_data option for your entire form class, see the cookbook article How to configure Empty Data for a Form Class
tipo: Boolean predeterminado: true
En muchos casos, si tienes un campo name, entonces esperas que setName sea invocado en el objeto subyacente. No obstante, en algunos casos, posiblemente setName no sea invocado. Al configurar by_reference te aseguras de que el definidor se llama en todos los casos.
Para explicar mejor esto, aquí tienes un sencillo ejemplo:
$builder = $this->createFormBuilder($article);
$builder
->add('title', 'text')
->add(
$builder->create('author', 'form', array('by_reference' => ?))
->add('name', 'text')
->add('email', 'email')
)
Si by_reference es true, lo siguiente se lleva a cabo tras bambalinas al llamar a bind en el formulario:
$article->setTitle('...');
$article->getAuthor()->setName('...');
$article->getAuthor()->setEmail('...');
Ten en cuenta que no se llama a setAuthor. El autor es modificado por referencia.
Si configuraste by_reference a falso, el vínculo se parece esto:
$article->setTitle('...');
$author = $article->getAuthor();
$author->setName('...');
$author->setEmail('...');
$article->setAuthor($author);
Por lo tanto, by_reference=false lo que realmente hace es forzar a la plataforma a llamar al definidor en el padre del objeto.
Del mismo modo, si estás usando el tipo Colección del formulario en el que los datos subyacentes de la colección son un objeto (como con ArrayCollection de Doctrine), entonces debes establecer by_reference a false si necesitas invocar al definidor (por ejemplo, setAuthors).
Estas opciones las hereda del tipo field:
tipo: Boolean predeterminado: true
Si es true, reproducirá un atributo required de HTML5. La label correspondiente será reproducida con una clase required.
Esto es superficial e independiente de la validación. A lo sumo, si dejas que Symfony deduzca el tipo de campo, entonces el valor de esta opción, se puede inferir a partir de tu información de validación.
tipo: string predefinido: La etiqueta se «deduce» a partir del nombre del campo
Establece la etiqueta que se utilizará al reproducir el campo. La etiqueta también se puede fijar directamente dentro de la plantilla:
{{ form_label(form.name, 'Tu nombre') }}
Nuevo en la versión 2.1: The read_only option was changed in 2.1 to render as a readonly HTML attribute. Previously, it rendered as a disabled attribute. Use the disabled option if you need the old behavior.
tipo: Boolean predeterminado: false
If this option is true, the field will be rendered with the readonly attribute so that the field is not editable.
Nuevo en la versión 2.1: The disabled option is new in version 2.1
type: boolean default: false
Si no deseas que un usuario pueda modificar el valor de un campo, puedes establecer la opción disabled en true. Cualquier valor recibido será omitido.
tipo: Boolean predeterminado: false
Si es true, los errores de este campo serán pasados al campo padre o al formulario. Por ejemplo, si estableces en true un campo normal, cualquier error de ese campo se adjuntará al formulario principal, no al campo específico.
These options inherit from the date type:
tipo: boolean default: false
This option determines if the form will be mapped with data. This can be useful if you need a form to structure the view. See Cómo usar la opción virtual en los campos de formulario.
