Controlli dei form

Panoramica dei controlli standard dei form.

addText (string $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput

Aggiunge un campo di testo a riga singola (classe TextInput). Se l'utente non compila il campo, restituisce una stringa vuota ''; usate setNullable() per fargli restituire invece null.

$form->addText('name', 'Nome:')
	->setRequired()
	->setNullable();

Valida automaticamente l'UTF-8, elimina gli spazi iniziali e finali e rimuove gli a capo che un aggressore potrebbe inviare.

La lunghezza massima si può limitare con setMaxLength(). Il metodo addFilter() permette di modificare il valore inserito dall'utente.

Con setHtmlType() potete cambiare l'aspetto visivo del campo di testo in tipi come search, tel o url, definiti nella specifica. Ricordate che cambiare il tipo è puramente visivo e non sostituisce la funzione di validazione. Per il tipo url conviene aggiungere un'apposita regola di validazione dell'URL.

Per gli altri tipi di input, come number, range, email, date, datetime-local, time e color, usate i metodi specializzati come addInteger(), addFloat(), addEmail(), addDate(), addTime(), addDateTime() e addColor(), che offrono la validazione lato server. I tipi month e week non sono ancora pienamente supportati da tutti i browser.

Al controllo si può impostare un “valore vuoto”. Funziona un po' come un valore predefinito, ma se l'utente non lo cambia, il controllo restituisce una stringa vuota oppure null.

$form->addText('phone', 'Telefono:')
	->setHtmlType('tel')
	->setEmptyValue('+420');

addTextArea (string $name, $label=null): TextArea

Aggiunge un campo di testo su più righe (classe TextArea). Se l'utente non compila il campo, restituisce una stringa vuota ''; usate setNullable() per fargli restituire invece null.

$form->addTextArea('note', 'Nota:')
	->addRule($form::MaxLength, 'La vostra nota è troppo lunga', 10000);

Valida automaticamente l'UTF-8 e normalizza i fine riga in \n. A differenza del campo a riga singola, non avviene alcuna eliminazione degli spazi.

La lunghezza massima si può limitare con setMaxLength(). Il metodo addFilter() permette di modificare il valore inserito dall'utente. Un valore vuoto si può impostare con setEmptyValue().

addInteger (string $name, $label=null): TextInput

Aggiunge un campo per inserire un numero intero (classe TextInput). Restituisce un intero oppure null se l'utente non inserisce nulla.

$form->addInteger('year', 'Anno:')
	->addRule($form::Range, 'L\'anno deve essere compreso tra %d e %d.', [1900, 2023]);

Il controllo viene disegnato come <input type="number">. Con il metodo setHtmlType() potete cambiare il tipo in range, per mostrarlo come cursore, oppure in text, se preferite un normale campo di testo senza il comportamento particolare del tipo number.

addFloat (string $name, $label=null): TextInput

Aggiunge un campo per inserire un numero in virgola mobile (classe TextInput). Restituisce un float oppure null se l'utente non inserisce nulla.

$form->addFloat('level', 'Livello:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Il livello deve essere compreso tra %d e %d.', [0, 100]);

Nette e il browser Chrome accettano come separatore decimale sia la virgola sia il punto. Per abilitare questa funzionalità anche in Firefox, conviene impostare l'attributo lang, sul singolo controllo oppure sull'intera pagina, per esempio <html lang="en">.

addEmail (string $name, $label=null, int $maxLength=255): TextInput

Aggiunge un campo per inserire un indirizzo e-mail (classe TextInput). Se l'utente non compila il campo, restituisce una stringa vuota ''; usate setNullable() per fargli restituire invece null.

$form->addEmail('email', 'E-mail:');

Valida che il valore sia un indirizzo e-mail valido. Non controlla se il dominio esista davvero, verifica solo la sintassi. Valida automaticamente l'UTF-8 ed elimina gli spazi iniziali e finali.

La lunghezza massima si può limitare con setMaxLength(). Il metodo addFilter() permette di modificare il valore inserito dall'utente. Un valore vuoto si può impostare con setEmptyValue().

addPassword (string $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput

Aggiunge un campo per la password (classe TextInput).

$form->addPassword('password', 'Password:')
	->setRequired()
	->addRule($form::MinLength, 'La password deve essere lunga almeno %d caratteri', 8)
	->addRule($form::Pattern, 'La password deve contenere un numero', '.*[0-9].*');

Quando il form viene mostrato di nuovo, il campo sarà vuoto. Valida automaticamente l'UTF-8, elimina gli spazi iniziali e finali e rimuove gli a capo che un aggressore potrebbe inviare.

addCheckbox (string $name, $caption=null): Checkbox

Aggiunge una checkbox (classe Checkbox). Restituisce true o false, a seconda che sia selezionata.

$form->addCheckbox('agree', 'Accetto le condizioni')
	->setRequired('Dovete accettare le nostre condizioni');

addCheckboxList (string $name, $label=null, ?array $items=null): CheckboxList

Aggiunge un elenco di checkbox per selezionare più elementi (classe CheckboxList). Restituisce un array delle chiavi degli elementi selezionati. Il metodo getSelectedItems() restituisce gli elementi selezionati come coppie chiave-valore.

$form->addCheckboxList('colors', 'Colori:', [
	'r' => 'rosso',
	'g' => 'verde',
	'b' => 'blu',
]);

Passate l'array degli elementi offerti come terzo parametro oppure con il metodo setItems(). Passando false come secondo argomento di setItems(), i valori vengono usati anche come chiavi.

Usate setDisabled(['r', 'g']) per disattivare singoli elementi.

Il controllo verifica automaticamente che non ci siano state falsificazioni e che gli elementi selezionati fossero davvero tra quelli offerti e non disattivati. Con il metodo getRawValue() si possono ottenere gli elementi inviati senza questo importante controllo.

Impostando gli elementi selezionati per impostazione predefinita, controlla anche che siano tra quelli offerti, altrimenti solleva un'eccezione. Questo controllo si può disattivare con checkDefaultValue(false).

Se inviate il form con il metodo GET, potete scegliere un modo di trasferimento dei dati più compatto, che riduce la dimensione della query string. Lo attivate impostando un attributo HTML sul form:

$form->setHtmlAttribute('data-nette-compact');

addRadioList (string $name, $label=null, ?array $items=null): RadioList

Aggiunge dei radio button (classe RadioList). Restituisce la chiave dell'elemento selezionato, oppure null se l'utente non ha selezionato nulla. Il metodo getSelectedItem() restituisce il valore invece della chiave.

$sex = [
	'm' => 'maschio',
	'f' => 'femmina',
	'o' => 'altro',
];
$form->addRadioList('gender', 'Sesso:', $sex);

Passate l'array degli elementi offerti come terzo parametro oppure con il metodo setItems().

Usate setDisabled(['m']) per disattivare singoli elementi.

Il controllo verifica automaticamente che non ci siano state falsificazioni e che l'elemento selezionato fosse davvero tra quelli offerti e non disattivato. Con il metodo getRawValue() si può ottenere l'elemento inviato senza questo importante controllo.

Impostando l'elemento selezionato per impostazione predefinita, controlla anche che sia tra quelli offerti, altrimenti solleva un'eccezione. Questo controllo si può disattivare con checkDefaultValue(false).

addSelect (string $name, $label=null, ?array $items=null, ?int $size=null): SelectBox

Aggiunge un select box (classe SelectBox). Restituisce la chiave dell'elemento selezionato, oppure null se l'utente non ha selezionato nulla. Il metodo getSelectedItem() restituisce il valore invece della chiave.

$countries = [
	'CZ' => 'Repubblica Ceca',
	'SK' => 'Slovacchia',
	'GB' => 'Regno Unito',
];

$form->addSelect('country', 'Paese:', $countries)
	->setDefaultValue('SK');

Passate l'array degli elementi offerti come terzo parametro oppure con il metodo setItems(). Gli elementi possono essere anche un array bidimensionale (che rappresenta gli optgroup):

$countries = [
	'Europa' => [
		'CZ' => 'Repubblica Ceca',
		'SK' => 'Slovacchia',
		'GB' => 'Regno Unito',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'altro',
];

Nei select box il primo elemento ha spesso un significato particolare, perché invita all'azione. Usate il metodo setPrompt() per aggiungere un elemento del genere.

$form->addSelect('country', 'Paese:', $countries)
	->setPrompt('Scegliete un paese');

Usate setDisabled(['CZ', 'SK']) per disattivare singoli elementi.

addMultiSelect (string $name, $label=null, ?array $items=null, ?int $size=null): MultiSelectBox

Aggiunge un select box per selezionare più elementi (classe MultiSelectBox). Restituisce un array delle chiavi degli elementi selezionati. Il metodo getSelectedItems() restituisce gli elementi selezionati come coppie chiave-valore.

$form->addMultiSelect('countries', 'Paesi:', $countries);

Passate l'array degli elementi offerti come terzo parametro oppure con il metodo setItems(). Gli elementi possono essere anche un array bidimensionale.

Usate setDisabled(['CZ', 'SK']) per disattivare singoli elementi.

addUpload (string $name, $label=null): UploadControl

Aggiunge un campo per caricare un file (classe UploadControl). Restituisce un oggetto FileUpload, anche se l'utente non ha caricato alcun file, cosa che si può verificare con il metodo FileUpload::hasFile(). Con setNullable() potete far restituire al controllo null invece di un oggetto FileUpload quando non viene caricato alcun file.

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'L\'avatar deve essere JPEG, PNG, GIF, WebP o AVIF.')
	->addRule($form::MaxFileSize, 'La dimensione massima è 1 MB.', 1024 * 1024);

Se il file non viene caricato correttamente, il form non viene inviato con successo e viene mostrato un errore. Dopo un invio riuscito, quindi, non è necessario controllare il metodo FileUpload::isOk().

Non fidatevi mai del nome originale del file restituito dal metodo FileUpload::getName(): il client potrebbe aver inviato un nome di file malevolo con l'intento di danneggiare o violare la vostra applicazione.

Le regole MimeType e Image rilevano il tipo richiesto in base alla firma del file e non ne verificano l'integrità. Se un'immagine sia danneggiata si può stabilire, per esempio, provando a caricarla.

addMultiUpload (string $name, $label=null): UploadControl

Aggiunge un campo per caricare più file in una volta (classe UploadControl). Restituisce un array di oggetti FileUpload. Il metodo FileUpload::hasFile() restituirà true per ciascuno di essi.

$form->addMultiUpload('files', 'File:')
	->addRule($form::MaxLength, 'Si possono caricare al massimo %d file.', 10);

Se qualche file non viene caricato correttamente, il form non viene inviato con successo e viene mostrato un errore. Dopo un invio riuscito, quindi, non è necessario controllare il metodo FileUpload::isOk() per ogni file.

Non fidatevi mai dei nomi originali dei file restituiti dal metodo FileUpload::getName(): il client potrebbe aver inviato nomi di file malevoli con l'intento di danneggiare o violare la vostra applicazione.

addDate (string $name, $label=null): DateTimeControl

Aggiunge un campo che permette all'utente di inserire facilmente una data composta da anno, mese e giorno (classe DateTimeControl).

Come valore predefinito accetta oggetti che implementano DateTimeInterface, una stringa che contiene un orario oppure un numero che rappresenta un timestamp UNIX. Lo stesso vale per gli argomenti delle regole Min, Max o Range, che definiscono la data minima e massima ammesse.

$form->addDate('date', 'Data:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'La data deve avere almeno un mese.', new DateTime('-1 month'));

Per impostazione predefinita restituisce un oggetto DateTimeImmutable. Con il metodo setFormat() potete indicare un formato testuale oppure un timestamp:

$form->addDate('date', 'Data:')
	->setFormat('Y-m-d');

addTime (string $name, $label=null, bool $withSeconds=false): DateTimeControl

Aggiunge un campo che permette all'utente di inserire facilmente un orario composto da ore, minuti ed eventualmente secondi (classe DateTimeControl).

Come valore predefinito accetta oggetti che implementano DateTimeInterface, una stringa che contiene un orario oppure un numero che rappresenta un timestamp UNIX. Di questi input viene usata solo l'informazione oraria; la data viene ignorata. Lo stesso vale per gli argomenti delle regole Min, Max o Range, che definiscono gli orari minimo e massimo ammessi. Se il valore minimo impostato è maggiore del massimo, si crea un intervallo orario che attraversa la mezzanotte.

$form->addTime('time', 'Ora:', withSeconds: true)
	->addRule($form::Range, 'L\'ora deve essere compresa tra %d e %d.', ['12:30', '13:30']);

Per impostazione predefinita restituisce un oggetto DateTimeImmutable (con la data impostata al 1° gennaio dell'anno 1). Con il metodo setFormat() potete indicare un formato testuale:

$form->addTime('time', 'Ora:')
	->setFormat('H:i');

addDateTime (string $name, $label=null, bool $withSeconds=false): DateTimeControl

Aggiunge un campo che permette all'utente di inserire facilmente data e ora insieme, composte da anno, mese, giorno, ore, minuti ed eventualmente secondi (classe DateTimeControl).

$form->addDateTime('datetime', 'Data e ora:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'La data deve avere almeno un mese.', new DateTime('-1 month'));

Per impostazione predefinita restituisce un oggetto DateTimeImmutable. Con il metodo setFormat() potete indicare un formato testuale oppure un timestamp:

$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);

addColor (string $name, $label=null): ColorPicker

Aggiunge un campo per scegliere un colore (classe ColorPicker). Il colore viene restituito come stringa nel formato #rrggbb. Se l'utente non effettua una scelta, restituisce il nero #000000.

$form->addColor('color', 'Colore:')
	->setDefaultValue('#3C8ED7');

addHidden (string $name, mixed $default=null): HiddenField

Aggiunge un campo nascosto (classe HiddenField).

$form->addHidden('userid');

Usate setNullable() per fargli restituire null invece di una stringa vuota. Il metodo addFilter() permette di modificare il valore inviato.

Benché il controllo sia nascosto, è importante rendersi conto che il suo valore può comunque essere modificato o falsificato da un aggressore. Verificate e validate sempre a fondo tutti i valori ricevuti sul lato server, per prevenire i rischi di sicurezza legati alla manipolazione dei dati.

addSubmit (string $name, $caption=null): SubmitButton

Aggiunge un pulsante di invio (classe SubmitButton).

$form->addSubmit('submit', 'Invia');

Il gestore si può passare direttamente al pulsante come terzo parametro $onSubmit, invece di agganciarlo all'evento onClick:

$form->addSubmit('submit', 'Invia', function (SubmitButton $button, $data): void {
	// ...
});

Nel form è possibile avere più di un pulsante di invio:

$form->addSubmit('register', 'Registrati');
$form->addSubmit('cancel', 'Annulla');

Per stabilire quale sia stato cliccato, usate:

if ($form['register']->isSubmittedBy()) {
  // ...
}

Se non volete validare l'intero form quando viene premuto un pulsante (per esempio per i pulsanti Annulla o Anteprima), usate setValidationScope().

addButton (string $name, $caption=null): Button

Aggiunge un pulsante (classe Button) che non ha la funzione di invio. Si può quindi usare per altre funzioni, per esempio per chiamare una funzione JavaScript al clic.

$form->addButton('raise', 'Aumenta lo stipendio')
	->setHtmlAttribute('onclick', 'raiseSalary()');

addImageButton (string $name, ?string $src=null, ?string $alt=null): ImageButton

Aggiunge un pulsante di invio sotto forma di immagine (classe ImageButton).

$form->addImageButton('submit', '/path/to/image.png', 'Invia');

Usando più pulsanti di invio, potete stabilire quale sia stato cliccato con $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Aggiunge un sotto-form (classe Container), cioè un container, nel quale si possono aggiungere altri controlli allo stesso modo in cui si aggiungono al form. Funzionano anche metodi come setDefaults() o getValues().

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Il vostro nome:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Il vostro nome:');
$sub2->addEmail('email', 'Email:');

I dati inviati vengono poi restituiti come struttura multidimensionale:

[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]

Panoramica delle impostazioni

Su tutti i controlli possiamo chiamare i metodi seguenti (per una panoramica completa vedi la documentazione dell'API):

`setDefaultValue($value)`	imposta il valore predefinito
`getValue()`	ottiene il valore corrente
`setOmitted()`	Valori omessi
`setDisabled()`	Disattivare i controlli

Rendering:

`setCaption($caption)`	cambia l'etichetta del controllo
`setTranslator($translator)`	imposta il traduttore
`setHtmlAttribute($name, $value)`	imposta un attributo HTML dell'elemento
`setHtmlId($id)`	imposta l'attributo HTML `id`
`setOption($key, $value)`	imposta le opzioni di rendering

Validazione:

`setRequired()`	rende il controllo obbligatorio
`addRule()`	aggiunge una regola di validazione
`addCondition()`, `addConditionOn()`	imposta una condizione di validazione
`addError($message)`	aggiunge un messaggio di errore

Sui controlli addText(), addPassword(), addTextArea(), addEmail(), addInteger(), addFloat() si possono chiamare i metodi seguenti:

`setNullable()`	imposta se getValue() restituisce `null` invece di una stringa vuota
`setEmptyValue($value)`	imposta un valore speciale considerato come stringa vuota
`setMaxLength($length)`	imposta il numero massimo di caratteri ammessi
`addFilter($filter)`	modifica l'input

Valori omessi

Se il valore compilato dall'utente non ci interessa, possiamo usare setOmitted() per escluderlo dal risultato del metodo $form->getValues() o dai dati passati ai gestori. È utile per i vari campi di conferma della password, per i controlli antispam e così via.

$form->addPassword('passwordVerify', 'Password di nuovo:')
	->setRequired('Inserite di nuovo la password per controllare eventuali errori di battitura')
	->addRule($form::Equal, 'Le password non coincidono', $form['password'])
	->setOmitted();

Disattivare i controlli

I controlli si possono disattivare con setDisabled(). Un controllo disattivato non può essere modificato dall'utente.

$form->addText('username', 'Nome utente:')
	->setDisabled();

I controlli disattivati non vengono inviati affatto dal browser al server, quindi non li troverete nei dati restituiti dalla funzione $form->getValues(). Se però impostate setOmitted(false), Nette includerà in questi dati il loro valore predefinito.

Quando viene chiamato setDisabled(), il valore del controllo viene azzerato per motivi di sicurezza. Se impostate un valore predefinito, dovete farlo dopo averlo disattivato:

$form->addText('username', 'Nome utente:')
	->setDisabled()
	->setDefaultValue($userName);

Un'alternativa ai controlli disattivati sono i controlli con l'attributo HTML readonly, che il browser invia al server. Benché il controllo sia di sola lettura, è importante rendersi conto che il suo valore può comunque essere modificato o falsificato da un aggressore.

Controlli personalizzati

Oltre all'ampia gamma di controlli integrati, potete aggiungere al form controlli personalizzati:

$form->addComponent(new DateInput('Data:'), 'date');
// sintassi alternativa: $form['date'] = new DateInput('Data:');

Come scrivere un controllo del genere, compresa la lettura dei dati inviati, la validazione e il rendering, è descritto in un capitolo a parte. Lì scoprirete anche i metodi di estensione, che vi permettono di creare un vostro metodo di aggiunta come $form->addZip().

Campi di basso livello

È possibile usare anche controlli scritti solo nel template e non aggiunti al form con nessuno dei metodi $form->addXyz(). Per esempio, elencando record da un database di cui non sappiamo in anticipo quanti saranno né quali saranno i loro ID, e volendo mostrare per ogni riga una checkbox o un radio button, possiamo semplicemente scriverlo nel template:

{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}

E dopo l'invio otteniamo il valore:

$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');

dove il primo parametro è il tipo di elemento (DataFile per type=file, DataLine per i campi a riga singola come text, password, email ecc., e DataText per tutti gli altri) e il secondo parametro sel[] corrisponde all'attributo HTML name. Possiamo combinare il tipo di elemento con il valore DataKeys, che conserva le chiavi degli elementi. È particolarmente utile per select, radioList e checkboxList.

Cosa essenziale, getHttpData() restituisce un valore ripulito. In questo caso sarà sempre un array di stringhe UTF-8 valide, indipendentemente da ciò che un aggressore possa provare a inviare al server. È l'analogo del lavorare direttamente con $_POST o $_GET, ma con la differenza sostanziale che restituisce sempre dati puliti, come siete abituati con i controlli standard dei form di Nette.