Tipo di campo entity

Un campo speciale choice pensato per caricare opzioni da un’entità Doctrine. Per esempio, se si ha un’entità Category, si può usare questo campo per mostrare un campo select di tutti, o di alcuni, oggetti Category presi dalla base dati.

Reso come possono essere vari tag (vedere Tag select, checkbox o bottoni radio)
Opzioni
Opzioni ridefinite
Opzioni ereditate

dal tipo choice:

dal tipo form:

Tipo genitore choice
Classe Symfony\Bridge\Doctrine\Form\Type\EntityType

Utilizzo di base

Il tipo entity ha una sola opzione obbligatoria: l’entità da elencare all’interno del campo choice:

$builder->add('users', 'entity', array(
    'class' => 'AcmeHelloBundle:User',
    'property' => 'username',
));

In questo caso, tutti gli oggetti User saranno caricati dalla base dati e resi come un tag select, dei radio o una serie di checkbox (a seconda dei valori di multiple ed expanded). Se l’oggetto entità manca del metodo __toString(), occorre passare l’opzione property.

Usare una query personalizzata per le entità

Se occorre specificare una query personalizzata da usare per recuperare le entità (p.e. si vogliono solo alcune entità o le si vuole ordinare), usare l’opzione query_builder. Il modo più facile è fare come segue:

use Doctrine\ORM\EntityRepository;
// ...

$builder->add('users', 'entity', array(
    'class' => 'AcmeHelloBundle:User',
    'query_builder' => function(EntityRepository $er) {
        return $er->createQueryBuilder('u')
            ->orderBy('u.username', 'ASC');
    },
));

Usare Choices

Se si dispone già della collezione di entità che si vuole includere nell’elemento choice, si può semplicemente passarla tramite l’opzione choices. Per esempio, se si ha una variabile $group (magari passata come opzione del form) e getUsers restitusice una collezione di entità User, si può fornire direttamente l’opzione choices:

$builder->add('users', 'entity', array(
    'class' => 'AcmeHelloBundle:User',
    'choices' => $group->getUsers(),
));

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

class

tipo: stringa required

La classe dell’entità (p.e. AcmeStoreBundle:Category). Può essere un nome di classe pienamente qualificato (p.e. Acme\StoreBundle\Entity\Category) o il suo alias (come mostrato sopra).

data_class

tipo: stringa

Questa opzione è usata per impostare il data mapper appropriato per l’uso con il form, in modo che si possa usarlo per qualsiasi tipo di campo che richieda un oggetto.

$builder->add('media', 'sonata_media_type', array(
    'data_class' => 'Acme\DemoBundle\Entity\Media',
));

em

tipo: stringa predefinito: il gestore di entità predefinito

Se specificato, il gestore di entità da usare per caricare le scelte, al posto di quello predefinito.

group_by

tipo: stringa

Il percorso di proprietà (p.e. author.name) usato per organizzare le scelte disponibili in gruppi. Funziona solo se reso come tag select e lo fa aggiungendo tag optgroup tra le opzioni. Le scelte che non restituiscono un valore per questo percorso di proprietà sono rese direttamente sotto il tag select, senza optgroup.

property

tipo: stringa

La proprietà da usare per mostrare le entità come testi nell’elemento HTML. Se lasciata vuota, gli oggetti saranno formattati come stringhe, quindi occorre avere un metodo __toString().

Nota

L’opzione property è il percorso della proprietà usato per mostrare l’opzione. Si può quindi usare qualsiasi cosa supportata dal componente PropertyAccessor

Per esempio, se la proprietà translations è un array associativo di oggetti, ciascuno con una proprietà name, si potrebbe fare così:

$builder->add('gender', 'entity', array(
   'class' => 'MyBundle:Gender',
   'property' => 'translations[en].name',
));

query_builder

tipo: Doctrine\ORM\QueryBuilder oppure una closure

Se specificato, è usato per cercare un sotto-insieme di opzioni (e il loro ordinamento) che dovrebbero essere usate per il campo. Il valore di questa opzione può essere un oggetto QueryBuilder oppure una closure. Se su usa una closure, dovrebbe accettare un singolo parametro, che è l’EntityRepository dell’entità.

Opzioni ridefinite

choice_list

predefinito: Symfony\Bridge\Doctrine\Form\ChoiceList\EntityChoiceList

Lo scopo del tipo entity è creare e configurare EntityChoiceList, usando una delle opzioni precedenti. Se occorre sovrascrivere questa opzione, si può prendere in considerazione l’uso diretto di Tipo di campo choice.

choices

tipo: array || \Traversable predefinito: null

Invece di lasciare che class e query_builder recuperino le entità da inserire, si può passare direttamente l’opzione choices. Vedere Usare Choices.

Opzioni ereditate

Queste opzioni sono ereditate dal tipo choice:

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.

Nota

Se si ha a che fare con una collezione di entità Doctrine, sarà utile leggere la documenzione anche di Tipo di campo collection. In aggiunta, c’è un esempio completo nella ricetta Unire una collezione di form.

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' => '=====')) ?>
    

Nota

Questa opzione si aspetta un array di oggetti entità, diversamente dal campo choice, che richiede un array di chiavi.

Queste opzioni sono ereditate dal tipo form:

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.

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

Se true, qualsiasi errore per questo campo sarà passato al campo genitore o al form. Per esempio, se impostato a true su un campo normale, qualsiasi errore per il campo sarà collegato al form principale, non al campo stesso.

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.

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.