Tipo di campo choice

Un campo multi-funzione, usato per consentire all’utente di scegliere una o più opzioni. Può essere reso come tag select, bottone radio o checkbox.

Per usare questo campo, bisogna specificare l’opzione choice_list oppure l’opzione choices.

Reso come può essere vari tag (vedere sotto)
Opzioni
Opzioni ridefinite
Opzioni ereditate
Tipo genitore form
Classe Symfony\Component\Form\Extension\Core\Type\ChoiceType

Esempio di utilizzo

Il modo più facile per usare questo campo è specificare le scelte direttamente con l’opzione choices. La chiave dell’array diventa il valore effettivamente impostato nell’oggetto (p.e. m), mentre il valore è quello che l’utente vede nel form (p.e. Maschio).

$builder->add('gender', 'choice', array(
    'choices'   => array('m' => 'Maschio', 'f' => 'Femmina'),
    'required'  => false,
));

Impostando multiple a true, si consente all’utente la scelta di più valori. Il widget sarà reso come un un tag select con opzione mutliple oppure come una serie di checkbox, a seconda dell’opzione expanded:

$builder->add('availability', 'choice', array(
    'choices'   => array(
        'morning'   => 'Mattina',
        'afternoon' => 'Pomeriggio',
        'evening'   => 'Sera',
    ),
    'multiple'  => true,
));

Si può anche usare l’opzione choice_list, che accetta un oggetto che può specificare le scelte per il widget.

Tag select, checkbox o bottoni radio

Questo campo può essere reso come uno tra diversi campi HTML, a seconda delle opzioni expanded e multiple:

tipo di elemento expanded multiple
tag select false false
tag select (con attributo multiple) false true
bottoni radio true false
checkbox true true

Opzioni del campo

choices

tipo: array predefinito: array()

Questo è il modo più semplice per specificare le scelte da usare per questo campo. L’opzione choices è un array, in cui le chiavi sono il valore dell’oggetto e i valori sono l’etichetta:

$builder->add('gender', 'choice', array(
    'choices' => array('m' => 'Maschio', 'f' => 'Femmina')
));

Suggerimento

Quando i valori tra cui scegliere non sono interi o stringhe (ma per esempio float o booleani), si dovrebbe usare invece l’opzione choice_list. Con tale opzione, si ha la possibilità di mantenere il formato originale dei dati, che è importante per assicurarsi una validazione corretta ed evitare inutili aggiornamenti sulla base dati, causati da una mancata corrispondenza tra tipi di dato.

choice_list

tipo: Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceListInterface

Questo è un modo per specificare le opzioni da usare per questo campo. L’opzione choice_list deve essere un’istanza di ChoiceListInterface. Per classi avanzate, si può creare una classe personalizzata che implementi questa interfaccia e fornisca le scelte.

Con questa opzione si possono anche aggiungere valori float, per essere selezionati come dati.

use Symfony\Component\Form\Extension\Core\ChoiceList\ChoiceList;

// ...
$builder->add('status', 'choice', array(
  'choice_list' => new ChoiceList(array(1, 0.5), array('Pieno', 'Metà')
));

placeholder

Nuovo nella versione 2.6: L’opzione placeholder è stata introdotta in Symfony 2.6, al posto di empty_value, che è disponibile per le versioni precedenti.

Nuovo nella versione 2.3: Da Symfony 2.3, si possono usare valori vuoti anche se l’opzione expanded è impostata a true.

tipo: stringa o booleano

Questa opzione determina se apparirà o meno una speciale opzione vuota (p.e. “Scegliere un’opzione”) in cima al select. Questa opzione si applica solamente se entrambe le opzioni expanded e multiple sono impostate a false.

  • Aggiungere un valore vuoto con “Scegliere un’opzione” come testo:

    $builder->add('states', 'choice', array(
        'placeholder' => 'Scegliere un\'opzione',
    ));
    
  • Non mostrare alcun valore vuoto:

    $builder->add('states', 'choice', array(
        'placeholder' => false,
    ));
    

Se non si imposta l’opzione placeholder, sarà aggiunta automaticamente un’opzione vuota (senza testo), ma solo se l’opzione required è false:

// sarà aggiunta un'opzione vuota (senza testo)
$builder->add('states', 'choice', array(
    'required' => false,
));

expanded

tipo: booleano predefinito: false

Se true, saranno resi dei bottoni radio o dei checkbox (a seconda del valore di multiple). Se false, sarà reso un elemento select.

multiple

tipo: booleano predefinito: false

Se true, l’utente potra selezionare più opzioni (invece di sceglierne una sola). A seconda del valore dell’opzione expanded, sarà reso o come un tag select o come dei checkbox, se true, e come un tag select o bottoni radio, se false. Il valore restituito sarà un array.

preferred_choices

tipo: array predefinito: array()

Se questa opzione viene specificata, un sotto-insieme di tutte le opzioni sarà spostato in cima al select. Il codice seguente sposterà l’opzione “Paperino” in cima, con un separatore visuale tra essa e le opzioni restanti:

$builder->add('scelte_pippo', 'choice', array(
    'choices' => array('pippo' => 'Pippo', 'pluto' => 'Pluto', 'paperino' => 'Paperino'),
    'preferred_choices' => array('paperino'),
));

Si noti che le scelte preferite hanno senso solo con la resa di un elemento select (cioè se expanded è false). Le scelte preferite e le scelte normali sono separate visivamente da una serie di righe (-------------------). Il separatore può essere personalizzato durante la resa:

  • Twig
    {{ form_widget(form.scelte_pippo, { 'separator': '=====' }) }}
    
  • PHP
    <?php echo $view['form']->widget($form['scelte_pippo'], array('separator' => '=====')) ?>
    

Opzioni ridefinite

compound

tipo: booleano predefinito: stesso valore dell’opzione expanded

Questa opzione specifica se il form è un composto. Il valore predefinito è sovrascritto dal valore dell’opzione expanded.

empty_data

tipo: mixed

Il valore predefinito effettivo di questa opzione dipende da altre opzioni:

  • Se multiple è false ed expanded è false, allora è '' (stringa vuota);
  • Altrimenti, è array() (array vuoto).

Questa opzione determina il valore restituito dal campo quando viene selezionato placeholder.

Si può personalizzare a seconda delle esigenze. Per esempio, se si vuole che il campo gender sia impostato a null quando non viene scelto alcun valore, lo si può fare in questo modo:

$builder->add('gender', 'choice', array(
    'choices' => array(
        'm' => 'Maschio',
        'f' => 'Femmina'
    ),
    'required'    => false,
    'placeholder' => 'Scegliere un genere',
    'empty_data'  => null
));

Nota

Se si vuole impostare l’opzione empty_data per l’intera classe del form, vedere la ricetta Configurare dati vuoti per una classe Form.

error_bubbling

tipo: booleano predefinito: false

Fa in modo che l’errore su questo campo sia allegato al campo stesso, invece che al campo genitore (il form, nella maggior parte dei casi).

Opzioni ereditate

Queste opzioni sono ereditate dal tipo form:

by_reference

tipo: Booleano predefinito: true

Se si ha un campo nome, ci si aspetta che setNome() venga invocato sull’oggetto sottostante. In alcuni casi, tuttavia, setNome() potrebbe non essere chiamato. Impostare by_reference assicura che il metodo setNome() sia sempre richiamato.

Per spiegare ciò, ecco un semplice esempio:

$builder = $this->createFormBuilder($article);
$builder
    ->add('title', 'text')
    ->add(
        $builder->create('author', 'form', array('by_reference' => ?))
            ->add('name', 'text')
            ->add('email', 'email')
    )

Se by_reference è true, il codice che segue viene eseguito dietro le quinte quando si invoca il metodo submit() (oppure handleRequest()) sul form:

$article->setTitle('...');
$article->getAuthor()->setName('...');
$article->getAuthor()->setEmail('...');

Notare che setAuthor() non è invocato. L’autore è modificato per riferimento.

Se si configura by_reference a false, all’invio dei dati viene eseguito il seguente codice:

$article->setTitle('...');
$author = $article->getAuthor();
$author->setName('...');
$author->setEmail('...');
$article->setAuthor($author);

Come si vede, quello che by_reference=false veramente implica è forzare il framework a chiamare il setter sull’oggetto relativo.

Similmente, se si usa il tipo collection, dove i tipi di dati nella collection sono oggetti (come per esempio gli ArrayCollection di Doctrine), by_reference deve essere configurata a false, se si vuole che il setter (p.e. setAuthors()) sia richiamato.

data

tipo: mixed predefinito: Predefinito al campo dell’oggetto sottostante (se presente)

Quando si crea un form, ogni campo inizialmente mostra il valore della proprietà corrispondente dell’oggetto del dominio del form (se un oggetto è legato al form). Se si vuole sovrascrivere il valore iniziale per il form o solo per un singolo campo, lo si può fare con l’opzione data:

$builder->add('token', 'hidden', array(
    'data' => 'abcdef',
));

disabled

type: booleano default: false

Se non si vuole che l’utente modifichi il valore di un campo, si può impostare questa opzione a true. Ogni valore inserito sarà ignorato.

error_mapping

tipo: array predefinito: empty

Questa opzione consente di modificare il bersaglio di un errore di validazione.

Si immagini di avere un metodo personalizzato, di nome matchingCityAndZipCode, che valida se una città e un codice postale corrsispondano. Purtroppo non c’è un campo “matchingCityAndZipCode” nel form, quindi tutto ciò che può fare Symfony è mostrare l’errore in cima al form stesso.

Con la mappatura personalizzata degli errori, si può fare meglio: mappare l’errore al campo della città, in modo che sia mostrato accanto a esso:

public function setDefaultOptions(OptionsResolverInterface $resolver)
{
    $resolver->setDefaults(array(
        'error_mapping' => array(
            'matchingCityAndZipCode' => 'city',
        ),
    ));
}

Ecco le regole per i lati destro e sinistro della mappatura:

  • I lato sinistro contiene i percorsi delle proprietà.
  • Se la validazione è generata su una proprietà o metodo di una classe, il suo percorso è semplicemente “nomeProprietà”.
  • Se la validazione è generata su un elemento di un array od oggetto ArrayAccess, il percorso è [nomeIndice].
  • Si possono costruire percorsi innestati, concatenandoli, separando le proprietà con dei punti. Per esempio: addresses[work].matchingCityAndZipCode
  • Anche il lato sinistro della mappatura accetta un punto ., che si riferisce al campo stesso. Questo significa che un errore aggiunto al campo è aggiunto invece al dato campo innnestato.
  • Il lato destro contiene semplicemente i nomi dei campi nel form.

inherit_data

Nuovo nella versione 2.3: Questa opzione era nota come virtual prima di Symfony 2.3.

tipo: booleano predefinito: false

Questa opzione determina se il form erediterà dati dal form genitore. Può essere utile se si ha un insieme di campi duplicati in form multipli. Vedere Ridurre la duplicazione di codice con “inherit_data”.

label

tipo: stringa predefinito: “indovinato” dal nome del campo

Imposta la label usata per la resa del campo. La label può anche essere inserita direttamente all’interno del template:

{{ form_label(form.name, 'Il tuo nome') }}

label_attr

tipo: array predefinito: array()

Imposta gli attributi HTML per l’elemento <label>, che saranno usati durante la resa della label di un campo. È un array associativo con gli attributi HTML come chiavi. Questi attributi possono anche essere impostati all’interno del template:

  • Twig
    {{ form_label(form.name, 'Nome', {'label_attr': {'class': 'CUSTOM_LABEL_CLASS'}}) }}
    
  • PHP
    echo $view['form']->label(
        $form['name'],
        'Nome',
        array('class', 'CUSTOM_LABEL_CLASS')
    );
    

mapped

tipo: booleano

Se si vuole che il campo sia ignorato durante la lettura o la scrittura dell’oggetto, si può impostare l’opzione mapped a false

read_only

tipo: booleano predefinito: false

Se questa opzione è true, il campo sarà reso con l’attributo disabled, in modo che il campo non sia modificabile.

required

tipo: booleano predefinito: true

Se true, sarà reso un attributo required HTML5. La label corrispondente sarà anche resa con una classe required.

L’attributo è indipendente dalla validazione del form. Nel caso migliore, se si lascia che Symfony indovini il tipo di campo, il valore di questa opzione sarà indovinato dalle informazioni di validazione.

Variabili di campo

Variabile Tipo Uso
multiple Booleano Il valore dell’opzione multiple.
expanded Booleano Il valore dell’opzione expanded.
preferred_choices array Un array con gli oggetti ChoiceView delle scelte che vanno mostrare all’utente con precedenza.
choices array Un array con gli oggetti ChoiceView delle scelte restanti.
separator stringa Il separatore da usare tra i gruppi.
placeholder mixed Il valore vuoto, se non già presente nella lista, altrimenti null.
is_selected callable Una funziona che accetta un ChoiceView e i valori selezionati e dice se la scelta fa parte dei valori selezionati.
placeholder_in_choices Booleano Se il valore vuoto è nella lista di scelte

Suggerimento

È molto più veloce usare invece il test selectedchoice(selected_value), quando si usa Twig.