Elementi del Form

Panoramica degli elementi standard del form.

addText (string|int $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 '', oppure tramite setNullable() è possibile specificare che restituisca null.

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

Valida automaticamente UTF-8, rimuove gli spazi iniziali e finali e rimuove gli a capo che un utente malintenzionato potrebbe inviare.

La lunghezza massima può essere limitata tramite setMaxLength(). Modificare il valore inserito dall'utente è possibile tramite addFilter().

Tramite setHtmlType() è possibile modificare l'aspetto visivo del campo di testo in tipi come search, tel o url, vedi specifiche. Ricorda che la modifica del tipo è solo visiva e non sostituisce la funzione di validazione. Per il tipo url è opportuno aggiungere una specifica regola URL.

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

All'elemento può essere impostato il cosiddetto empty-value, che è qualcosa come un valore predefinito, ma se l'utente non lo modifica, l'elemento restituisce una stringa vuota o null.

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

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

Aggiunge un campo per l'inserimento di testo multilinea (classe TextArea). Se l'utente non compila il campo, restituisce una stringa vuota '', oppure tramite setNullable() è possibile specificare che restituisca null.

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

Valida automaticamente UTF-8 e normalizza i separatori di riga in \n. A differenza del campo di input a riga singola, non viene eseguita alcuna rimozione degli spazi.

La lunghezza massima può essere limitata tramite setMaxLength(). Modificare il valore inserito dall'utente è possibile tramite addFilter(). È possibile impostare il cosiddetto empty-value tramite setEmptyValue().

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

Aggiunge un campo per l'inserimento di un numero intero (classe TextInput). Restituisce un intero o 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]);

L'elemento viene renderizzato come <input type="number">. Utilizzando il metodo setHtmlType() è possibile cambiare il tipo in range per la visualizzazione come slider, o in text se si preferisce un campo di testo standard senza il comportamento speciale del tipo number.

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

Aggiunge un campo per l'inserimento di un numero decimale (classe TextInput). Restituisce un float o 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 sia la virgola che il punto come separatore decimale. Affinché questa funzionalità sia disponibile anche in Firefox, si consiglia di impostare l'attributo lang per l'elemento specifico o per l'intera pagina, ad esempio <html lang="it">.

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

Aggiunge un campo per l'inserimento di un indirizzo email (classe TextInput). Se l'utente non compila il campo, restituisce una stringa vuota '', oppure tramite setNullable() è possibile specificare che restituisca null.

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

Verifica se il valore è un indirizzo email valido. Non verifica se il dominio esiste realmente, verifica solo la sintassi. Valida automaticamente UTF-8, rimuove gli spazi iniziali e finali.

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

Aggiunge un campo per l'inserimento della password (classe TextInput).

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

Alla successiva visualizzazione del form, il campo sarà vuoto. Valida automaticamente UTF-8, rimuove gli spazi iniziali e finali e rimuove gli a capo che un utente malintenzionato potrebbe inviare.

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

Aggiunge una casella di controllo (classe Checkbox). Restituisce il valore true o false, a seconda che sia selezionata o meno.

$form->addCheckbox('agree', 'Accetto i termini e le condizioni')
	->setRequired('È necessario accettare i termini e le condizioni');

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

Aggiunge caselle di controllo per la selezione di più elementi (classe CheckboxList). Restituisce un array delle chiavi degli elementi selezionati. Il metodo getSelectedItems() restituisce i valori invece delle chiavi.

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

L'array degli elementi offerti viene passato come terzo parametro o tramite il metodo setItems().

Tramite setDisabled(['r', 'g']) è possibile disattivare singoli elementi.

L'elemento controlla automaticamente che non ci sia stato un tentativo di manomissione e che gli elementi selezionati siano effettivamente tra quelli offerti e non siano stati disattivati. Tramite il metodo getRawValue() è possibile ottenere gli elementi inviati senza questo importante controllo.

Durante l'impostazione degli elementi selezionati predefiniti, controlla anche che siano tra quelli offerti, altrimenti genera un'eccezione. Questo controllo può essere disattivato tramite checkDefaultValue(false).

Se invii il form con il metodo GET, puoi scegliere un modo più compatto per trasferire i dati, che risparmia la dimensione della query string. Si attiva impostando l'attributo HTML del form:

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

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

Aggiunge pulsanti di opzione (classe RadioList). Restituisce la chiave dell'elemento selezionato, o null se l'utente non ha selezionato nulla. Il metodo getSelectedItem() restituisce il valore invece della chiave.

$sex = [
	'm' => 'uomo',
	'f' => 'donna',
];
$form->addRadioList('gender', 'Sesso:', $sex);

L'array degli elementi offerti viene passato come terzo parametro o tramite il metodo setItems().

Tramite setDisabled(['m', 'f']) è possibile disattivare singoli elementi.

L'elemento controlla automaticamente che non ci sia stato un tentativo di manomissione e che l'elemento selezionato sia effettivamente uno di quelli offerti e non sia stato disattivato. Tramite il metodo getRawValue() è possibile ottenere l'elemento inviato senza questo importante controllo.

Durante l'impostazione dell'elemento selezionato predefinito, controlla anche che sia uno di quelli offerti, altrimenti genera un'eccezione. Questo controllo può essere disattivato tramite checkDefaultValue(false).

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

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

$countries = [
	'IT' => 'Italia',
	'DE' => 'Germania',
	'GB' => 'Regno Unito',
];

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

L'array degli elementi offerti viene passato come terzo parametro o tramite il metodo setItems(). Gli elementi possono essere anche un array bidimensionale:

$countries = [
	'Europa' => [
		'IT' => 'Italia',
		'DE' => 'Germania',
		'GB' => 'Regno Unito',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'altro',
];

Nei select box, spesso il primo elemento ha un significato speciale, serve come invito all'azione. Per aggiungere un tale elemento serve il metodo setPrompt().

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

Tramite setDisabled(['IT', 'DE']) è possibile disattivare singoli elementi.

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

Aggiunge un select box per la selezione di più elementi (classe MultiSelectBox). Restituisce un array delle chiavi degli elementi selezionati. Il metodo getSelectedItems() restituisce i valori invece delle chiavi.

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

L'array degli elementi offerti viene passato come terzo parametro o tramite il metodo setItems(). Gli elementi possono essere anche un array bidimensionale.

Tramite setDisabled(['IT', 'DE']) è possibile disattivare singoli elementi.

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

Aggiunge un campo per l'upload di un file (classe UploadControl). Restituisce un oggetto FileUpload anche nel caso in cui l'utente non abbia inviato alcun file, il che può essere verificato con il metodo FileUpload::hasFile().

$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 visualizzato un errore. Cioè, in caso di invio riuscito, non è necessario verificare il metodo FileUpload::isOk().

Non fidarti mai del nome originale del file restituito dal metodo FileUpload::getName(), il client potrebbe aver inviato un nome di file dannoso con l'intenzione di danneggiare o hackerare la tua applicazione.

Le regole MimeType e Image rilevano il tipo richiesto in base alla firma del file e non ne verificano l'integrità. Se l'immagine non è danneggiata può essere verificato, ad esempio, tentando di caricarla.

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

Aggiunge un campo per l'upload di più file contemporaneamente (classe UploadControl). Restituisce un array di oggetti FileUpload. Il metodo FileUpload::hasFile() per ciascuno di essi restituirà true.

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

Se uno qualsiasi dei file non viene caricato correttamente, il form non viene inviato con successo e viene visualizzato un errore. Cioè, in caso di invio riuscito, non è necessario verificare il metodo FileUpload::isOk().

Non fidarti mai dei nomi originali dei file restituiti dal metodo FileUpload::getName(), il client potrebbe aver inviato un nome di file dannoso con l'intenzione di danneggiare o hackerare la tua applicazione.

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

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

Come valore predefinito accetta oggetti che implementano l'interfaccia DateTimeInterface, una stringa con l'ora o un numero che rappresenta il timestamp UNIX. Lo stesso vale per gli argomenti delle regole Min, Max o Range, che definiscono la data minima e massima consentita.

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

Standard restituisce un oggetto DateTimeImmutable, con il metodo setFormat() puoi specificare il formato testuale o timestamp:

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

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

Aggiunge un campo che consente all'utente di inserire facilmente un'ora composta da ore, minuti e facoltativamente secondi (classe DateTimeControl).

Come valore predefinito accetta oggetti che implementano l'interfaccia DateTimeInterface, una stringa con l'ora o un numero che rappresenta il timestamp UNIX. Da questi input viene utilizzata solo l'informazione sull'ora, la data viene ignorata. Lo stesso vale per gli argomenti delle regole Min, Max o Range, che definiscono l'ora minima e massima consentita. Se il valore minimo impostato è superiore al massimo, viene creato un intervallo di tempo che supera la mezzanotte.

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

Standard restituisce un oggetto DateTimeImmutable (con data 1 gennaio anno 1), con il metodo setFormat() puoi specificare il formato testuale:

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

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

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

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

Standard restituisce un oggetto DateTimeImmutable, con il metodo setFormat() puoi specificare il formato testuale o timestamp:

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

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

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

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

addHidden (string|int $name, ?string $default=null): HiddenField

Aggiunge un campo nascosto (classe HiddenField).

$form->addHidden('userid');

Tramite setNullable() è possibile impostare che restituisca null invece di una stringa vuota. Modificare il valore inviato è possibile tramite addFilter().

Sebbene l'elemento sia nascosto, è importante rendersi conto che il valore può ancora essere modificato o falsificato da un utente malintenzionato. Verifica e convalida sempre attentamente tutti i valori ricevuti lato server per prevenire rischi di sicurezza associati alla manipolazione dei dati.

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

Aggiunge un pulsante di invio (classe SubmitButton).

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

Nel form è possibile avere anche più pulsanti di invio:

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

Per scoprire su quale di essi è stato cliccato, usa:

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

Se non vuoi validare l'intero form alla pressione del pulsante (ad esempio per i pulsanti Annulla o Anteprima), usa setValidationScope().

addButton (string|int $name, $caption): Button

Aggiunge un pulsante (classe Button), che non ha funzione di invio. Può quindi essere utilizzato per qualche altra funzione, ad esempio chiamare una funzione JavaScript al clic.

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

addImageButton (string|int $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');

Utilizzando più pulsanti di invio, è possibile scoprire su quale è stato cliccato tramite $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Aggiunge un sottoform (classe Container), ovvero un contenitore, al quale è possibile aggiungere altri elementi nello stesso modo in cui li aggiungiamo al form. Funzionano anche i metodi setDefaults() o getValues().

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

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

I dati inviati vengono quindi restituiti come una struttura multidimensionale:

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

Panoramica delle impostazioni

Su tutti gli elementi possiamo chiamare i seguenti metodi (panoramica completa nella documentazione API):

`setDefaultValue($value)`	imposta il valore predefinito
`getValue()`	ottiene il valore attuale
`setOmitted()`	Omissione del valore
`setDisabled()`	Disattivazione degli elementi

Renderizzazione:

`setCaption($caption)`	modifica l'etichetta dell'elemento
`setTranslator($translator)`	imposta il traduttore
`setHtmlAttribute($name, $value)`	imposta l'attributo HTML dell'elemento
`setHtmlId($id)`	imposta l'attributo HTML `id`
`setHtmlType($type)`	imposta l'attributo HTML `type`
`setHtmlName($name)`	imposta l'attributo HTML `name`
`setOption($key, $value)`	impostazione per la renderizzazione

Validazione:

`setRequired()`	elemento obbligatorio
`addRule()`	imposta la regola di validazione
`addCondition()`, `addConditionOn()`	imposta la condizione di validazione
`addError($message)`	passaggio del messaggio di errore

Sugli elementi addText(), addPassword(), addTextArea(), addEmail(), addInteger() è possibile chiamare i seguenti metodi:

`setNullable()`	imposta se getValue() restituirà `null` invece di una stringa vuota
`setEmptyValue($value)`	imposta un valore speciale che viene considerato come stringa vuota
`setMaxLength($length)`	imposta il numero massimo di caratteri consentiti
`addFilter($filter)`	modifica dell'input

Omissione del valore

Se il valore compilato dall'utente non ci interessa, possiamo ometterlo dal risultato del metodo $form->getValues() o dai dati passati agli handler tramite setOmitted(). Questo è utile per varie password di controllo, elementi antispam, ecc.

$form->addPassword('passwordVerify', 'Password di controllo:')
	->setRequired('Inserisci nuovamente la password per controllo')
	->addRule($form::Equal, 'Le password non corrispondono', $form['password'])
	->setOmitted();

Disattivazione degli elementi

Gli elementi possono essere disattivati tramite setDisabled(). Un tale elemento non può essere modificato dall'utente.

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

Gli elementi disabilitati non vengono inviati dal browser al server, quindi non li troverete nei dati restituiti dalla funzione $form->getValues(). Tuttavia, se impostate setOmitted(false), Nette includerà in questi dati il loro valore predefinito.

Quando si chiama setDisabled(), per motivi di sicurezza il valore dell'elemento viene cancellato. Se si imposta un valore predefinito, è necessario farlo dopo la sua disattivazione:

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

Un'alternativa agli elementi disabilitati sono gli elementi con l'attributo HTML readonly, che il browser invia al server. Sebbene l'elemento sia solo di lettura, è importante rendersi conto che il suo valore può ancora essere modificato o falsificato da un utente malintenzionato.

Elementi personalizzati

Oltre alla vasta gamma di elementi di form integrati, è possibile aggiungere elementi personalizzati al form in questo modo:

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

Il form è un discendente della classe Container e i singoli elementi sono discendenti di Component.

Esiste un modo per definire nuovi metodi del form che servono ad aggiungere elementi personalizzati (es. $form->addZip()). Si tratta delle cosiddette extension methods. Lo svantaggio è che per esse non funzionerà il suggerimento negli editor.

use Nette\Forms\Container;

// aggiungiamo il metodo addZip(string $name, ?string $label = null)
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'Almeno 5 numeri', '[0-9]{5}');
});

// utilizzo
$form->addZip('zip', 'Codice postale:');

Elementi di basso livello

È possibile utilizzare anche elementi che scriviamo solo nel template e non aggiungiamo al form con uno dei metodi $form->addXyz(). Ad esempio, quando elenchiamo record da un database e non sappiamo in anticipo quanti ce ne saranno e quali ID avranno, e vogliamo visualizzare una checkbox o un radio button per ogni riga, basta codificarlo nel template:

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

E dopo l'invio scopriamo 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 input a riga singola come text, password, email ecc. e DataText per tutti gli altri) e il secondo parametro sel[] corrisponde all'attributo HTML name. Il tipo di elemento può essere combinato con il valore DataKeys, che conserva le chiavi degli elementi. Questo è particolarmente utile per select, radioList e checkboxList.

È essenziale che getHttpData() restituisca un valore sanificato, in questo caso sarà sempre un array di stringhe UTF-8 valide, indipendentemente da ciò che un utente malintenzionato potrebbe tentare di inviare al server. È analogo al lavoro diretto con $_POST o $_GET, ma con la differenza sostanziale che restituisce sempre dati puliti, come siete abituati con gli elementi standard dei form Nette.