Costruire il Form¶

Ora che la classe Task è stata creata, il prossimo passo è creare e visualizzare il form HTML. In Symfony2, lo si fa costruendo un oggetto form e poi visualizzandolo in un template. Per ora, lo si può fare all'interno di un controllore:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// src/Acme/TaskBundle/Controller/DefaultController.php
namespace Acme\TaskBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Acme\TaskBundle\Entity\Task;
use Symfony\Component\HttpFoundation\Request;

class DefaultController extends Controller
{
    public function newAction(Request $request)
    {
        // crea un task fornendo alcuni dati fittizi per questo esempio
        $task = new Task();
        $task->setTask('Scrivere un post sul blog');
        $task->setDueDate(new \DateTime('tomorrow'));

        $form = $this->createFormBuilder($task)
            ->add('task', 'text')
            ->add('dueDate', 'date')
            ->getForm();

        return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
            'form' => $form->createView(),
        ));
    }
}

La creazione di un form richiede relativamente poco codice, perché gli oggetti form di Symfony2 sono costruiti con un "costruttore di form". Lo scopo del costruttore di form è quello di consentire di scrivere una semplice "ricetta" per il form e fargli fare tutto il lavoro pesante della costruzione del form.

In questo esempio sono stati aggiunti due campi al form, task e dueDate, corrispondenti alle proprietà task e dueDate della classe Task. È stato anche assegnato un "tipo" ciascuno (ad esempio text, date), che, tra le altre cose, determina quale tag form HTML viene utilizzato per tale campo.

Symfony2 ha molti tipi predefiniti che verranno trattati a breve (see Tipi di campo predefiniti).

Visualizzare il Form¶

Ora che il modulo è stato creato, il passo successivo è quello di visualizzarlo. Questo viene fatto passando uno speciale oggetto form "view" al template (notare il $form->createView() nel controllore sopra) e utilizzando una serie di funzioni helper per i form:

Questo è tutto! Scrivendo form_widget(form), ciascun campo del form viene reso, insieme a un'etichetta e a un messaggio di errore (se presente). Per quanto semplice, questo metodo non è molto flessibile (ancora). Di solito, si ha bisogno di rendere individualmente ciascun campo in modo da poter controllare la visualizzazione del form. Si imparerà a farlo nella sezione "Rendere un form in un template".

Prima di andare avanti, notare come il campo input task reso ha il value della proprietà task dall'oggetto $task (ad esempio "Scrivere un post sul blog"). Questo è il primo compito di un form: prendere i dati da un oggetto e tradurli in un formato adatto a essere reso in un form HTML.

Gestione dell'invio del form¶

Il secondo compito di un form è quello di tradurre i dati inviati dall'utente alle proprietà di un oggetto. Affinché ciò avvenga, i dati inviati dall'utente devono essere associati al form. Aggiungere le seguenti funzionalità al controllore:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// ...
use Symfony\Component\HttpFoundation\Request;

public function newAction(Request $request)
{
    // crea un nuovo oggetto $task (rimuove i dati fittizi)
    $task = new Task();

    $form = $this->createFormBuilder($task)
        ->add('task', 'text')
        ->add('dueDate', 'date')
        ->getForm();

    if ($request->isMethod('POST')) {
        $form->bind($request);

        if ($form->isValid()) {
            // esegue alcune azioni, come ad esempio salvare il task nella base dati

            return $this->redirect($this->generateUrl('task_success'));
        }
    }

    // ...
}

New in version 2.1: Il metodo bind è stato resto più flessibile in Symfony 2.1. Ora accetta i dati grezzi del client (come prima) o un oggetto Request di Symfony. È da preferire al metodo deprecato bindRequest.

Ora, quando si invia il form, il controllore associa i dati inviati al form, che traduce nuovamente i dati alle proprietà task e dueDate dell'oggetto $task. Tutto questo avviene attraverso il metodo bindRequest().

Questo controllore segue uno schema comune per gestire i form e ha tre possibili percorsi:

1. Quando in un browser inizia il caricamento di una pagina, il metodo request è GET e il form è semplicemente creato e reso;
2. Quando l'utente invia il form (cioè il metodo è POST) con dati non validi (la validazione è trattata nella sezione successiva), il form è associato e poi reso, questa volta mostrando tutti gli errori di validazione;
3. Quando l'utente invia il form con dati validi, il form viene associato e si ha la possibilità di eseguire alcune azioni usando l'oggetto $task (ad esempio persistendo i dati nella base dati) prima di rinviare l'utente a un'altra pagina (ad esempio una pagina "thank you" o "success").

Gruppi di validatori¶

Se un oggetto si avvale dei gruppi di validatori, occorrerà specificare quali gruppi di convalida deve usare il form:

1
2
3

$form = $this->createFormBuilder($users, array(
    'validation_groups' => array('registrazione'),
))->add(...);

Se si stanno creando classi per i form (una buona pratica), allora si avrà bisogno di aggiungere quanto segue al metodo setDefaultOptions():

1
2
3
4
5
6
7
8

use Symfony\Component\OptionsResolver\OptionsResolverInterface;

public function setDefaultOptions(OptionsResolverInterface $resolver)
{
    $resolver->setDefaults(array(
        'validation_groups' => array('registrazione')
    ));
}

In entrambi i casi, solo il gruppo di validazione registrazione verrà utilizzato per validare l'oggetto sottostante.

Gruppi basati su dati inseriti¶

New in version 2.1: La possibilità di specificare un callback o una Closure in validation_groups è stata aggiunta nella versione 2.1

Se si ha bisogno di una logica avanzata per determinare i gruppi di validazione (p.e. basandosi sui dati inseriti), si può impostare l'opzione validation_groups a un callback o a una Closure:

1
2
3
4
5
6
7
8

use Symfony\Component\OptionsResolver\OptionsResolverInterface;

public function setDefaultOptions(OptionsResolverInterface $resolver)
{
    $resolver->setDefaults(array(
        'validation_groups' => array('Acme\\AcmeBundle\\Entity\\Client', 'determineValidationGroups'),
    ));
}

Questo richiamerà il metodo statico determineValidationGroups() della classe Client, dopo il bind del form ma prima dell'esecuzione della validazione. L'oggetto Form è passato come parametro del metodo (vedere l'esempio successivo). Si può anche definire l'intera logica con una Closure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

use Symfony\Component\Form\FormInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;

public function setDefaultOptions(OptionsResolverInterface $resolver)
{
    $resolver->setDefaults(array(
        'validation_groups' => function(FormInterface $form) {
            $data = $form->getData();
            if (Entity\Client::TYPE_PERSON == $data->getType()) {
                return array('person');
            } else {
                return array('company');
            }
        },
    ));
}

Campi testo¶

• text
• textarea
• email
• integer
• money
• number
• password
• percent
• search
• url

Campi di scelta¶

• choice
• entity
• country
• language
• locale
• timezone

Campi data e ora¶

• date
• datetime
• time
• birthday

Altri campi¶

• checkbox
• file
• radio

Gruppi di campi¶

• collection
• repeated

Campi nascosti¶

• hidden
• csrf

Campi di base¶

• field
• form

È anche possibile creare dei tipi di campi personalizzati. Questo argomento è trattato nell'articolo "Come creare un tipo di campo personalizzato di un form" del ricettario.

Opzioni dei tipi di campo¶

Ogni tipo di campo ha un numero di opzioni che può essere utilizzato per la configurazione. Ad esempio, il campo dueDate è attualmente reso con 3 menu select. Tuttavia, il campo data può essere configurato per essere reso come una singola casella di testo (in cui l'utente deve inserire la data nella casella come una stringa):

1

->add('dueDate', 'date', array('widget' => 'single_text'))

Ogni tipo di campo ha un numero di opzioni differente che possono essere passate a esso. Molte di queste sono specifiche per il tipo di campo e i dettagli possono essere trovati nella documentazione di ciascun tipo.

1
2
3
4

->add('dueDate', 'date', array(
    'widget' => 'single_text',
    'label'  => 'Due Date',
))

Indovinare le opzioni dei tipi di campo¶

Oltre a indovinare il "tipo" di un campo, Symfony può anche provare a indovinare i valori corretti di una serie di opzioni del campo.

• required: L'opzione required può essere indovinata in base alle regole di validazione (cioè se il campo è NotBlank o NotNull) o dai metadati di Doctrine (vale a dire se il campo è nullable). Questo è molto utile, perché la validazione lato client corrisponderà automaticamente alle vostre regole di validazione.
• max_length: Se il campo è un qualche tipo di campo di testo, allora l'opzione max_length può essere indovinata dai vincoli di validazione (se viene utilizzato Length o Range) o dai meta-dati Doctrine (tramite la lunghezza del campo).

Se si desidera modificare uno dei valori indovinati, è possibile sovrascriverlo passando l'opzione nell'array di opzioni del campo:

1

->add('task', null, array('max_length' => 4))

Rendere manualmente ciascun campo¶

L'helper form_row è utile perché si può rendere ciascun campo del form molto facilmente (e il markup utilizzato per la "riga" può essere personalizzato come si vuole). Ma poiché la vita non è sempre così semplice, è anche possibile rendere ogni campo interamente a mano. Il risultato finale del codice che segue è lo stesso di quando si è utilizzato l'helper form_row:

Se l'etichetta auto-generata di un campo non è giusta, si può specificarla esplicitamente:

Alcuni tipi di campi hanno opzioni di resa aggiuntive che possono essere passate al widget. Queste opzioni sono documentate con ogni tipo, ma un'opzione comune è attr, che permette di modificare gli attributi dell'elemento form. Di seguito viene aggiunta la classe task_field al resa del campo casella di testo:

Se occorre rendere dei campi "a mano", si può accedere ai singoli valori dei campi, come id, name e label. Per esempio, per ottenere id:

Per ottenere il valore usato per l'attributo nome dei campi del form, occorre usare il valore full_name:

Riferimento alle funzioni del template Twig¶

Se si utilizza Twig, un riferimento completo alle funzioni di resa è disponibile nel manuale di riferimento. Leggendolo si può sapere tutto sugli helper disponibili e le opzioni che possono essere usate con ciascuno di essi.

Incorporare un oggetto singolo¶

Supponiamo che ogni Task appartenga a un semplice oggetto Category. Si parte, naturalmente, con la creazione di un oggetto Category:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// src/Acme/TaskBundle/Entity/Category.php
namespace Acme\TaskBundle\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Category
{
    /**
     * @Assert\NotBlank()
     */
    public $name;
}

Poi, aggiungere una nuova proprietà category alla classe Task:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// ...

class Task
{
    // ...

    /**
     * @Assert\Type(type="Acme\TaskBundle\Entity\Category")
     */
    protected $category;

    // ...

    public function getCategory()
    {
        return $this->category;
    }

    public function setCategory(Category $category = null)
    {
        $this->category = $category;
    }
}

Ora che l'applicazione è stata aggiornata per riflettere le nuove esigenze, creare una classe di form in modo che l'oggetto Category possa essere modificato dall'utente:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// src/Acme/TaskBundle/Form/Type/CategoryType.php
namespace Acme\TaskBundle\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;

class CategoryType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('name');
    }

    public function setDefaultOptions(OptionsResolverInterface $resolver)
    {
        $resolver->setDefaults(array(
            'data_class' => 'Acme\TaskBundle\Entity\Category',
        ));
    }

    public function getName()
    {
        return 'category';
    }
}

L'obiettivo finale è quello di far si che la Category di un Task possa essere correttamente modificata all'interno dello stesso form task. Per farlo, aggiungere il campo category all'oggetto TaskType, il cui tipo è un'istanza della nuova classe CategoryType:

1
2
3
4
5
6
7
8

use Symfony\Component\Form\FormBuilderInterface;

public function buildForm(FormBuilderInterface $builder, array $options)
{
    // ...

    $builder->add('category', new CategoryType());
}

I campi di CategoryType ora possono essere resi accanto a quelli della classe TaskType. Per attivare la validazione su CategoryType, aggiungere l'opzione cascade_validation a TaskType:

1
2
3
4
5
6
7

public function setDefaultOptions(OptionsResolverInterface $resolver)
{
    $resolver->setDefaults(array(
        'data_class' => 'Acme\TaskBundle\Entity\Task',
        'cascade_validation' => true,
    ));
}

Rendere i campi di Category allo stesso modo dei campi Task originali:

Quando l'utente invia il form, i dati inviati con i campi Category sono utilizzati per costruire un'istanza di Category, che viene poi impostata sul campo category dell'istanza Task.

L'istanza Category è accessibile naturalmente attraverso $task->getCategory() e può essere memorizzata nella base dati o utilizzata quando serve.

Incorporare un insieme di form¶

È anche possibile incorporare un insieme di form in un form (si immagini un form Category con tanti sotto-form Product. Lo si può fare utilizzando il tipo di campo collection.

Per maggiori informazioni, vedere la ricetta "Come unire una collezione di form" e il riferimento al tipo collection.

Nomi per i frammenti di form¶

In Symfony, ogni parte di un form che viene reso (elementi HTML del form, errori, etichette, ecc.) è definito in un tema base, che in Twig è una raccolta di blocchi e in PHP una collezione di file template.

In Twig, ogni blocco necessario è definito in un singolo file template (form_div_layout.html.twig) che si trova all'interno di Twig Bridge. Dentro questo file, è possibile ogni blocco necessario alla resa del form e ogni tipo predefinito di campo.

In PHP, i frammenti sono file template individuali. Per impostazione predefinita sono posizionati nella cartella Resources/views/Form del bundle framework (vedere su GitHub).

Ogni nome di frammento segue lo stesso schema di base ed è suddiviso in due pezzi, separati da un singolo carattere di sottolineatura (_). Alcuni esempi sono:

• field_row - usato da form_row per rendere la maggior parte dei campi;
• textarea_widget - usato da form_widget per rendere un campo di tipo textarea;
• field_errors - usato da form_errors per rendere gli errori di un campo;

Ogni frammento segue lo stesso schema di base: type_part. La parte type corrisponde al campo type che viene reso (es. textarea, checkbox, date, ecc) mentre la parte part corrisponde a cosa si sta rendendo (es. label, widget, errors, ecc). Per impostazione predefinita, ci sono 4 possibili parti di un form che possono essere rese:

Conoscendo il tipo di campo (ad esempio textarea) e che parte si vuole personalizzare (ad esempio widget), si può costruire il nome del frammento che deve essere sovrascritto (esempio textarea_widget).

Ereditarietà dei frammenti di template¶

In alcuni casi, il frammento che si vuole personalizzare sembrerà mancare. Ad esempio, non c'è nessun frammento textarea_errors nei temi predefiniti forniti con Symfony. Quindi dove sono gli errori di un campo textarea che deve essere reso?

La risposta è: nel frammento field_errors. Quando Symfony rende gli errori per un tipo textarea, prima cerca un frammento textarea_errors, poi cerca un frammento form_errors. Ogni tipo di campo ha un tipo genitore (il tipo genitore di textarea è text) e Symfony utilizza il frammento per il tipo del genitore se il frammento di base non esiste.

Quindi, per ignorare gli errori dei soli campi textarea, copiare il frammento form_errors, rinominarlo in textarea_errors e personalizzrlo. Per sovrascrivere la resa degli errori predefiniti di tutti i campi, copiare e personalizzare direttamente il frammento form_errors.

Temi globali per i form¶

Nell'esempio sopra, è stato utilizzato l'helper form_theme (in Twig) per "importare" i frammenti personalizzati solo in quel form. Si può anche dire a Symfony di importare personalizzazioni del form nell'intero progetto.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{% extends '::base.html.twig' %}

{# import "_self" as the form theme #}
{% form_theme form _self %}

{# make the form fragment customization #}
{% block form_row %}
    {# custom field row output #}
{% endblock form_row %}

{% block content %}
    {# ... #}

    {{ form_row(form.task) }}
{% endblock %}

Aggiungere la validazione¶

L'ultima parte mancante è la validazione. Solitamente, quando si richiama $form->isValid(), l'oggetto viene validato dalla lettura dei vincoli applicati alla classe. Se il form è legato a un oggetto (cioè se si sta usando l'opzione data_class o passando un oggetto al form), questo è quasi sempre l'approccio desiderato. Vedere Validazione per maggiori dettagli.

Ma se il form non è legato a un oggetto e invece si sta recuperando un semplice array di dati inviati, come si possono aggiungere vincoli al form?

La risposta è: impostare i vincoli in modo autonomo e passarli al form. L'approccio generale è spiegato meglio nel capitolo sulla validazione, ma ecco un breve esempio:

New in version 2.1: L'opzione constraints, che accetta un singolo vincolo o un array di vincoli (prima della 2.1, l'opzione era chiamata validation_constraint e accettava solo un singolo vincolo) è nuova in Symfony 2.1.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

use Symfony\Component\Validator\Constraints\Length;
use Symfony\Component\Validator\Constraints\NotBlank;

$builder
   ->add('firstName', 'text', array(
       'constraints' => new Length(array('min' => 3)),
   ))
   ->add('lastName', 'text', array(
       'constraints' => array(
           new NotBlank(),
           new Length(array('min' => 3)),
       ),
   ))
;

1

new NotBlank(array('groups' => array('create', 'update'))