Tipo di campo form

Il tipo form predefinisce alcune opzioni, che sono quindi disponibili su tutti i campi che hanno form come genitore:

Opzioni
Opzioni ereditate
Genitore nessuno
Classe Symfony\Component\Form\Extension\Core\Type\FormType

Opzioni del campo

Nuovo nella versione 2.3: L’opzione action è stata introdotta in Symfony 2.3.

action

tipo: stringa predefinito: stringa vuota

Questa opzione specifica dove inviare i dati del form (solitamente un URI). Il suo valore viene reso come attributo action dell’elemento form. Un valore vuoto viene considerato come riferimento allo stesso documento, cioè il form sarà inviato allo stesso URI che ha reso il form.

allow_extra_fields

Nuovo nella versione 2.6: L’opzione allow_extra_fields è stata introdotta in Symfony 2.6.

tipo: booleano predefinito: false

Di solito, se si inviano campi che non sono stati configurati in un form, si ottiene un errore “This form should not contain extra fields.”.

Si può evitare tale errore, abilitando l’opzione allow_extra_fields nel 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.

cascade_validation

tipo: booleano predefinito: false

Impostare questa opzione a true per forzare la validazione su form inclusi. Per esempio, se si ha un ProductType con incluso CategoryType, impostare cascade_validation a true su ProductType farà validare anche i dati di CategoryType.

Invece di usare questa opzione, si può anche usare il vincolo Valid nel modello, per forzare la validazione di un oggetto figlio memorizzato su una proprietà.

Suggerimento

Per impostazione predefinita, l’opzione error_bubbling è abilitata per il tipo di campo collection, che passa gli errori al form genitore. Se si vogliono allegare gli errori alle posizioni in cui sono effettivamente avvenuti, occorre impostare error_bubbling a false.

compound

tipo: booleano

Questa opzione specifica se un form è composto. Questo non dipende dal fatto che il form abbia o meno dei figli. Un form può essere composto ma non avere alcun figlio (p.e. un form costituito da una collection vuota).

constraints

tipo: array o Symfony\Component\Validator\Constraint predefinito: null

Consente di allegare uno o più vincoli di validazione a un campo specifico. Per maggiori informazioni, vedere aggiungere la validazione. Questa opzione è aggiunta nell’estensione del form Symfony\Component\Form\Extension\Validator\Type\FormTypeValidatorExtension.

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',
));

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',
));

empty_data

tipo: mixed

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

  • Se data_class è impostato e required è true, allora new $data_class();
  • Se data_class è impostato e required è false, allora null;
  • Se data_class non è impostato e compound è true, allora array() (empty array);
  • Se data_class non è impostato e compound è false, allora '' (stringa vuota).

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.

extra_fields_message

tipo: stringa predefinito: This form should not contain extra fields.

Il messaggio di errore usato se i dati inviati al form contengono campi che non fanno parte della definizione del form stesso. Si può usare il segnaposto {{ extra_fields }} per mostrare un elenco di nomi di campi extra.

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”.

invalid_message

tipo: stringa predefinito: This value is not valid

Questo è il messaggio di errore di validazione usato quando i dati inseriti sono determinati dalla validazione interna di un tipo di campo. Questo può accadere, per esempio, se l’utente inserire una stringa dentro un campo time che non può essere convertito in un tempo reale. Per i normali messaggi di validazione (come quando si imposta la lunghezza minima per un campo), impostare i messaggi di validazione con le proprie regole di validazione (riferimento).

invalid_message_parameters

tipo: array predefinito: array()

Impostando l’opzione invalid_message, si potrebbe aver bisogno di includere alcune variabili nella stringa. Lo si può fare aggiungendo dei segnaposto all’opzione e includendo le variabili in questa opzione:

$builder->add('un_campo', 'un_tipo', array(
    // ...
    'invalid_message'            => 'Valore inserito non valido: deve includere almeno %num% caratteri',
    'invalid_message_parameters' => array('%num%' => 6),
));

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

Attenzione

L’opzione max_length è stata deprecata e sarà rimossa in 3.0. Usare invece l’opzione attr, impostandola a un array con una chiave maxlength.

max_length

tipo: intero

Se questa opzione non è nulla, aggiunge un attributo max_length, usato da alcuni browser per limitare la lunghezza del testo in un campo.

La validazione è solo su browser, quindi i dati devono essere comunque validati lato server.

Nuovo nella versione 2.3: L’opzione method è stata introdotta in Symfony 2.3.

method

tipo: stringa predefinito: POST

Questa opzione specifica il metodo HTTP da usare per il form. Il suo valore viene reso come attributo method dell’elemento form ed è usato per decidere se processare o meno il form, nel metodo handleRequest(). Valori possibili sono:

  • POST
  • GET
  • PUT
  • DELETE
  • PATCH

pattern

tipo: stringa predefinito: null

Aggiunge un attributo HTML5 pattern per restringere un campo input tramite un’espressione regolare.

post_max_size_message

tipo: stringa predefinito: The uploaded file was too large. Please try to upload a smaller file.

Il messaggio di errore usato se i dati inviati in POST eccedono la direttiva post_max_size di php.ini. Si può usare il segnaposto {{ max }} per mostrare la dimensione consentita.

property_path

tipo: qualsiasi predefinito: il valore del campo

I campi mostrano il valore di una proprietà dell’oggetto del dominio del form. Quando il form è inviato, il valore immesso è scritto nell’oggetto.

Se si vuole sovrascrivere la proprietà che un campo legge e scrive, si può impostare l’opzione property_path. Il suo valore predefinito è il nome del campo.

Se si vuole che il campo sia ignorato in lettura o in scrittura dell’oggetto, si può impostare l’opzione property_path 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.

trim

tipo: booleano predefinito: true

Se true, gli spazi vuoti della stringa inviata saranno eliminati, tramite la funzione trim(). Questo garantisce che se un valore viene inserito con spazi vuoti superflui, questi vengano rimossi prima che il valore sia inserito nell’oggetto sottostante.

Opzioni ereditate

Le seguenti opzioni sono definite nella classe Symfony\Component\Form\Extension\Core\Type\BaseType. La classe BaseType è la classe genitore sia del tipo form sia del tipo button, ma non fa parte dell’albero dei tipi di form (cioè non può essere usata a sua volta come tipo di form).

attr

tipo: array predefinito: array vuoto

Se si vogliono aggiungere attributi extra a un campo HTML, si può usare l’opzione attr. È un array associativo con attributi HTML come chiavi. Può essere utile quando occorre impostare una classe personalizzata per un widget:

$builder->add('body', 'textarea', array(
    'attr' => array('class' => 'tinymce'),
));

auto_initialize

tipo: booleano predefinito: true

Un’opzione interna: dice se il form va inizializzato automaticamente. Per tutti i campi, questa opzione dovrebbe ssere true per form radice. Non occorre cambiare questa opzione e probabilmente non sarà necessario preoccuparsene.

block_name

tipo: stringa predefinito: il nome del form (vedere sapere quale blocco personalizzare)

Consente di ridefinire il nome del blocco usato per rendere il form type. Utile per esempio se si hanno più istanze dello stesso form e occorre personalizzare la resa dei form individualmente.

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.

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') }}

translation_domain

tipo: stringa predefinito: messages

Il dominio di traduzione che sarà usato per qualsiasi label o option rese per questo campo.