Nette Documentation Preview

syntax
Controlli del modulo
********************

.[perex]
Panoramica dei controlli di modulo incorporati.


addText(string|int $name, $label=null): TextInput .[method]
===========================================================

Aggiunge un campo di testo a riga singola (classe [TextInput |api:Nette\Forms\Controls\TextInput]). Se l'utente non compila il campo, restituisce una stringa vuota `''`, oppure si può usare `setNullable()` per modificarlo e restituire `null`.

```php
$form->addText('name', 'Name:')
	->setRequired()
	->setNullable();
```

Convalida automaticamente UTF-8, taglia gli spazi bianchi a destra e a sinistra e rimuove le interruzioni di riga che potrebbero essere inviate da un utente malintenzionato.

La lunghezza massima può essere limitata utilizzando `setMaxLength()`. Il metodo [addFilter() |validation#Modifying Input Values] consente di modificare il valore inserito dall'utente.

Utilizzando `setHtmlType()`, è possibile cambiare il [carattere |https://developer.mozilla.org/en-US/docs/Learn/Forms/HTML5_input_types] dell'elemento di input in `search`, `tel`, `url`, `range`, `month`, `week`, o `color`. Per altri tipi, come `number`, `email`, `date`, `datetime-local` e `time`, esistono metodi separati [addInteger |#addInteger], [addFloat |#addFloat], [addEmail |#addEmail], [addDate |#addDate], [addTime |#addTime] e [addDateTime |#addDateTime], dotati di validazione lato server.

```php
$form->addText('color', 'Choose color:')
	->setHtmlType('color')
	->addRule($form::Pattern, 'invalid value', '[0-9a-f]{6}');
```

È possibile impostare il cosiddetto valore vuoto per l'elemento, che è qualcosa di simile al valore predefinito, ma se l'utente non lo sovrascrive, restituisce una stringa vuota o `null`.

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


addTextArea(string|int $name, $label=null): TextArea .[method]
==============================================================

Aggiunge un campo di testo multilinea (classe [TextArea |api:Nette\Forms\Controls\TextArea]). Se l'utente non compila il campo, restituisce una stringa vuota `''`, oppure si può usare `setNullable()` per modificarlo e restituire `null`.

```php
$form->addTextArea('note', 'Note:')
	->addRule($form::MaxLength, 'Your note is way too long', 10000);
```

Convalida automaticamente UTF-8 e normalizza le interruzioni di riga a `\n`. A differenza di un campo di input a una riga, non taglia gli spazi bianchi.

La lunghezza massima può essere limitata utilizzando `setMaxLength()`. Il metodo [addFilter() |validation#Modifying Input Values] consente di modificare il valore immesso dall'utente. È possibile impostare il cosiddetto valore vuoto utilizzando `setEmptyValue()`.


addInteger(string|int $name, $label=null): TextInput .[method]
==============================================================

Aggiunge un campo di input per numeri interi (classe [TextInput |api:Nette\Forms\Controls\TextInput]). Restituisce un intero o `null` se l'utente non inserisce nulla.

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


addFloat(string|int $name, $label=null): TextInput .[method]{data-version:3.1.12}
=================================================================================

Adds a field for entering a decimal number ([TextInput |api:Nette\Forms\Controls\TextInput] class). Returns either float or `null`, if the user does not specify anything.

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

Nette e Chrome accettano sia la virgola che il punto come separatore decimale. Affinché anche Firefox accetti la virgola, è necessario impostare la lingua corrispondente nell'attributo HTML `lang`, direttamente a questo elemento o a qualsiasi elemento padre, ad esempio `<html lang="cs">`.


addEmail(string|int $name, $label=null): TextInput .[method]
============================================================

Aggiunge un campo per l'indirizzo e-mail con controllo di validità (classe [TextInput |api:Nette\Forms\Controls\TextInput]). Se l'utente non compila il campo, restituisce una stringa vuota `''`, oppure si può usare `setNullable()` per modificarlo e restituire `null`.

```php
$form->addEmail('email', 'Email:');
```

Verifica che il valore sia un indirizzo e-mail valido. Non verifica l'effettiva esistenza del dominio, ma solo la sintassi. Convalida automaticamente UTF-8, taglia gli spazi bianchi a destra e a sinistra.

La lunghezza massima può essere limitata utilizzando `setMaxLength()`. Il metodo [addFilter() |validation#Modifying Input Values] consente di modificare il valore inserito dall'utente. È possibile impostare il cosiddetto valore vuoto utilizzando `setEmptyValue()`.


addPassword(string|int $name, $label=null): TextInput .[method]
===============================================================

Aggiunge il campo password (classe [TextInput |api:Nette\Forms\Controls\TextInput]).

```php
$form->addPassword('password', 'Password:')
	->setRequired()
	->addRule($form::MinLength, 'Password has to be at least %d characters long', 8)
	->addRule($form::Pattern, 'Password must contain a number', '.*[0-9].*');
```

Quando si invia nuovamente il modulo, l'input sarà vuoto. Convalida automaticamente UTF-8, taglia gli spazi bianchi a destra e a sinistra e rimuove le interruzioni di riga che potrebbero essere inviate da un utente malintenzionato.


addCheckbox(string|int $name, $caption=null): Checkbox .[method]
================================================================

Aggiunge una casella di controllo (classe [Checkbox |api:Nette\Forms\Controls\Checkbox]). Il campo restituisce `true` o `false`, a seconda che sia selezionato o meno.

```php
$form->addCheckbox('agree', 'I agree with terms')
	->setRequired('You must agree with our terms');
```


addCheckboxList(string|int $name, $label=null, array $items=null): CheckboxList .[method]
=========================================================================================

Aggiunge un elenco di caselle di controllo per la selezione di più elementi (classe [CheckboxList |api:Nette\Forms\Controls\CheckboxList]). Restituisce l'array di chiavi degli elementi selezionati. Il metodo `getSelectedItems()` restituisce i valori invece delle chiavi.

```php
$form->addCheckboxList('colors', 'Colors:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);
```

Si passa l'array di elementi come terzo parametro o con il metodo `setItems()`.

È possibile utilizzare `setDisabled(['r', 'g'])` per disabilitare singoli elementi.

L'elemento controlla automaticamente che non ci siano state contraffazioni e che gli elementi selezionati siano effettivamente tra quelli proposti e non siano stati disabilitati. Il metodo `getRawValue()` può essere utilizzato per recuperare gli elementi inviati senza questo importante controllo.

Quando sono impostati dei valori predefiniti, controlla anche che siano uno degli elementi offerti, altrimenti lancia un'eccezione. Questo controllo può essere disattivato con `checkDefaultValue(false)`.


addRadioList(string|int $name, $label=null, array $items=null): RadioList .[method]
===================================================================================

Aggiunge pulsanti di opzione (classe [RadioList |api:Nette\Forms\Controls\RadioList]). Restituisce la chiave dell'elemento selezionato o `null` se l'utente non ha selezionato nulla. Il metodo `getSelectedItem()` restituisce un valore invece di una chiave.

```php
$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);
```

Si passa l'array di elementi come terzo parametro o con il metodo `setItems()`.

È possibile utilizzare `setDisabled(['m'])` per disabilitare singoli elementi.

L'elemento controlla automaticamente che non ci siano state contraffazioni e che l'elemento selezionato sia effettivamente uno di quelli proposti e non sia stato disabilitato. Il metodo `getRawValue()` può essere utilizzato per recuperare l'elemento inviato senza questo importante controllo.

Quando il valore predefinito è impostato, controlla anche che sia uno degli elementi offerti, altrimenti lancia un'eccezione. Questo controllo può essere disattivato con `checkDefaultValue(false)`.


addSelect(string|int $name, $label=null, array $items=null): SelectBox .[method]
================================================================================

Aggiunge una casella di selezione (classe [SelectBox |api:Nette\Forms\Controls\SelectBox]). Restituisce la chiave dell'elemento selezionato o `null` se l'utente non ha selezionato nulla. Il metodo `getSelectedItem()` restituisce un valore invece di una chiave.

```php
$countries = [
	'CZ' => 'Czech republic',
	'SK' => 'Slovakia',
	'GB' => 'United Kingdom',
];

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

Si passa l'array di elementi come terzo parametro o con il metodo `setItems()`. L'array di elementi può anche essere bidimensionale:

```php
$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];
```

Per le caselle di selezione, il primo elemento ha spesso un significato speciale, in quanto funge da invito all'azione. Utilizzare il metodo `setPrompt()` per aggiungere una voce di questo tipo.

```php
$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');
```

È possibile utilizzare `setDisabled(['CZ', 'SK'])` per disabilitare singole voci.

L'elemento controlla automaticamente che non ci siano state contraffazioni e che l'elemento selezionato sia effettivamente uno di quelli proposti e non sia stato disabilitato. Il metodo `getRawValue()` può essere utilizzato per recuperare l'elemento inviato senza questo importante controllo.

Quando il valore predefinito è impostato, controlla anche che sia uno degli elementi offerti, altrimenti lancia un'eccezione. Questo controllo può essere disattivato con `checkDefaultValue(false)`.


addMultiSelect(string|int $name, $label=null, array $items=null): MultiSelectBox .[method]
==========================================================================================

Aggiunge una casella di selezione a scelta multipla (classe [MultiSelectBox |api:Nette\Forms\Controls\MultiSelectBox]). Restituisce l'array di chiavi degli elementi selezionati. Il metodo `getSelectedItems()` restituisce i valori invece delle chiavi.

```php
$form->addMultiSelect('countries', 'Countries:', $countries);
```

La matrice di elementi viene passata come terzo parametro o con il metodo `setItems()`. L'array di elementi può anche essere bidimensionale.

È possibile utilizzare `setDisabled(['CZ', 'SK'])` per disabilitare singoli elementi.

L'elemento controlla automaticamente che non ci siano state contraffazioni e che gli elementi selezionati siano effettivamente tra quelli proposti e non siano stati disabilitati. Il metodo `getRawValue()` può essere utilizzato per recuperare gli elementi inviati senza questo importante controllo.

Quando sono impostati dei valori predefiniti, controlla anche che siano uno degli elementi offerti, altrimenti lancia un'eccezione. Questo controllo può essere disattivato con `checkDefaultValue(false)`.


addUpload(string|int $name, $label=null): UploadControl .[method]
=================================================================

Aggiunge il campo di caricamento dei file (classe [UploadControl |api:Nette\Forms\Controls\UploadControl]). Restituisce l'oggetto [FileUpload |http:request#FileUpload], anche se l'utente non ha caricato un file, cosa che può essere scoperta con il metodo `FileUpload::hasFile()`.

```php
$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatar must be JPEG, PNG, GIF or WebP')
	->addRule($form::MaxFileSize, 'Maximum size is 1 MB', 1024 * 1024);
```

Se il file non è stato caricato correttamente, il modulo non è stato inviato con successo e viene visualizzato un errore. Non è quindi necessario controllare il metodo `FileUpload::isOk()`.

Non fidatevi del nome originale del file restituito dal metodo `FileUpload::getName()`, un client potrebbe inviare un nome di file dannoso con l'intenzione di corrompere o hackerare l'applicazione.

Le regole `MimeType` e `Image` rilevano il tipo di file o immagine richiesto in base alla sua firma. L'integrità dell'intero file non viene controllata. È possibile scoprire se un'immagine non è danneggiata, ad esempio provando a [caricarla |http:request#toImage].


addMultiUpload(string|int $name, $label=null): UploadControl .[method]
======================================================================

Aggiunge un campo per il caricamento di più file (classe [UploadControl |api:Nette\Forms\Controls\UploadControl]). Restituisce un array di oggetti [FileUpload |http:request#FileUpload]. Il metodo `FileUpload::hasFile()` restituirà `true` per ciascuno di essi.

```php
$form->addMultiUpload('files', 'Files:')
	->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);
```

Se uno dei file non viene caricato correttamente, il modulo non è stato inviato correttamente e viene visualizzato un errore. Non è quindi necessario controllare il metodo `FileUpload::isOk()`.

Non fidatevi dei nomi originali dei file restituiti dal metodo `FileUpload::getName()`, un client potrebbe inviare un nome di file dannoso con l'intenzione di corrompere o hackerare l'applicazione.

Le regole `MimeType` e `Image` rilevano il tipo di file o immagine richiesto in base alla sua firma. L'integrità dell'intero file non viene controllata. È possibile scoprire se un'immagine non è danneggiata, ad esempio provando a [caricarla |http:request#toImage].


addDate(string|int $name, $label=null): DateTimeControl .[method]{data-version:3.1.14}
======================================================================================

Aggiunge un campo che consente all'utente di inserire facilmente una data composta da anno, mese e giorno (classe [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Per il valore predefinito, accetta o oggetti che implementano la regola `DateTimeInterface`, una stringa con l'ora o 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 consentita.

```php
$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));
```

Per impostazione predefinita, restituisce un oggetto `DateTimeImmutable`. Utilizzando il metodo `setFormat()`, è possibile specificare un [formato di testo |https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] o un timestamp:

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


addTime(string|int $name, $label=null, bool $withSeconds = false): DateTimeControl .[method]{data-version:3.1.14}
=================================================================================================================

Aggiunge un campo che consente all'utente di inserire facilmente il tempo composto da ore, minuti e, facoltativamente, secondi (classe [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Per il valore predefinito, accetta oggetti che implementano `DateTimeInterface`, una stringa con l'ora o un numero che rappresenta un timestamp UNIX. Solo le informazioni sull'ora di questi input vengono utilizzate; la data viene ignorata. Lo stesso vale per gli argomenti delle regole `Min`, `Max`, o `Range`, che definiscono il tempo minimo e massimo consentito. Se il valore minimo impostato è superiore a quello massimo, viene creato un intervallo di tempo che copre la mezzanotte.

```php
$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);
```

Per impostazione predefinita, restituisce un oggetto `DateTimeImmutable` (con data 1 gennaio, anno 1). Utilizzando il metodo `setFormat()`, è possibile specificare un [formato di testo |https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters]:

```php
$form->addTime('time', 'Time:')
	->setFormat('H:i');
```


addDateTime(string|int $name, $label=null, bool $withSeconds = false): DateTimeControl .[method]{data-version:3.1.14}
=====================================================================================================================

Aggiunge un campo che consente all'utente di inserire facilmente sia la data che l'ora, composta da anno, mese, giorno, ore, minuti e, facoltativamente, secondi (classe [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Per il valore predefinito, accetta sia oggetti che implementano `DateTimeInterface`, sia una stringa con l'ora, sia 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 consentita.

```php
$form->addDateTime('datetime', 'Date and Time:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));
```

Per impostazione predefinita, restituisce un oggetto `DateTimeImmutable`. Utilizzando il metodo `setFormat()`, è possibile specificare un [formato di testo |https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] o un timestamp:

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


addColor(string|int $name, $label=null): ColorPicker .[method]{data-version:3.1.14}
===================================================================================

Aggiunge un campo di selezione del colore (classe [ColorPicker |api:Nette\Forms\Controls\ColorPicker]). Il colore è una stringa nel formato `#rrggbb`. Se l'utente non effettua alcuna selezione, il colore predefinito restituito è il nero `#000000`.

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


addHidden(string|int $name, string $default=null): HiddenField .[method]
========================================================================

Aggiunge un campo nascosto (classe [HiddenField |api:Nette\Forms\Controls\HiddenField]).

```php
$form->addHidden('userid');
```

Utilizzare `setNullable()` per modificarlo in modo che restituisca `null` invece di una stringa vuota. Il metodo [addFilter() |validation#Modifying Input Values] consente di modificare il valore inviato.


addSubmit(string|int $name, $caption=null): SubmitButton .[method]
==================================================================

Aggiunge il pulsante di invio (classe [SubmitButton |api:Nette\Forms\Controls\SubmitButton]).

```php
$form->addSubmit('submit', 'Register');
```

È possibile avere più di un pulsante di invio nel modulo:

```php
$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');
```

Per sapere quale di essi è stato cliccato, utilizzare:

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

Se non si desidera convalidare il modulo quando viene premuto un pulsante di invio (come i pulsanti *Cancel* o *Preview*), è possibile disattivarlo con [setValidationScope() |validation#Disabling Validation].


addButton(string|int $name, $caption): Button .[method]
=======================================================

Aggiunge un pulsante (classe [Button |api:Nette\Forms\Controls\Button]) senza funzione di invio. È utile per legare altre funzionalità all'id, ad esempio un'azione JavaScript.

```php
$form->addButton('raise', 'Raise salary')
	->setHtmlAttribute('onclick', 'raiseSalary()');
```


addImageButton(string|int $name, string $src=null, string $alt=null): ImageButton .[method]
===========================================================================================

Aggiunge un pulsante di invio sotto forma di immagine (classe [ImageButton |api:Nette\Forms\Controls\ImageButton]).

```php
$form->addImageButton('submit', '/path/to/image');
```

Quando si usano più pulsanti di invio, si può sapere quale è stato cliccato con `$form['submit']->isSubmittedBy()`.


addContainer(string|int $name): Container .[method]
===================================================

Aggiunge un sub-form (classe [Container |api:Nette\Forms\Container]), o un contenitore, che può essere trattato come un form. Ciò significa che si possono usare metodi come `setDefaults()` o `getValues()`.

```php
$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Your name:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Your name:');
$sub2->addEmail('email', 'Email:');
```

I dati inviati vengono restituiti come struttura multidimensionale:

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


Panoramica delle impostazioni .[#toc-overview-of-settings]
==========================================================

Per tutti gli elementi si possono richiamare i seguenti metodi (si veda la [documentazione dell'API |https://api.nette.org/forms/master/Nette/Forms/Controls.html] per una panoramica completa):

.[table-form-methods language-php]
| `setDefaultValue($value)` | imposta il valore predefinito
| `getValue()` | ottiene il valore corrente
| `setOmitted()` | [omettere i valori |#omitted values]
| `setDisabled()` | [disabilitare gli ingressi |#disabling inputs]

Rendering:
.[table-form-methods language-php]
| `setCaption($caption)`| modifica la didascalia dell'elemento
| `setTranslator($translator)` | imposta [il traduttore |rendering#translating]
| `setHtmlAttribute($name, $value)` | imposta l'[attributo HTML |rendering#HTML attributes] 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)` | imposta i [dati di rendering |rendering#Options]

Convalida:
.[table-form-methods language-php]
| `setRequired()` | [campo obbligatorio |validation]
| `addRule()` | imposta [regola di validazione |validation#Rules]
| `addCondition()`, `addConditionOn()` | impostare [condizione di validazione |validation#Conditions]
| `addError($message)`| [passaggio del messaggio di errore |validation#processing-errors]

I seguenti metodi possono essere richiamati per gli elementi `addText()`, `addPassword()`, `addTextArea()`, `addEmail()`, `addInteger()`:

.[table-form-methods language-php]
| `setNullable()`| imposta se getValue() restituisce `null` invece della stringa vuota
| `setEmptyValue($value)` | imposta il valore speciale che viene trattato come stringa vuota
| `setMaxLength($length)`| imposta il numero massimo di caratteri consentiti
| `addFilter($filter)`| [modificare i valori di input |validation#Modifying Input Values]


Valori omessi .[#toc-omitted-values]
------------------------------------

Se non si è interessati al valore inserito dall'utente, si può usare `setOmitted()` per ometterlo dal risultato fornito dal metodo `$form->getValues​()` o passato ai gestori. Questo è adatto per varie password di verifica, campi antispam, ecc.

```php
$form->addPassword('passwordVerify', 'Password again:')
	->setRequired('Fill your password again to check for typo')
	->addRule($form::Equal, 'Password mismatch', $form['password'])
	->setOmitted();
```


Disabilitazione degli ingressi .[#toc-disabling-inputs]
-------------------------------------------------------

Per disabilitare un input, si può chiamare `setDisabled()`. Questo campo non può essere modificato dall'utente.

```php
$form->addText('username', 'User name:')
	->setDisabled();
```

I campi disabilitati non vengono inviati dal browser al server, quindi non sono presenti nei dati restituiti dalla funzione `$form->getValues()`. Tuttavia, se si imposta `setOmitted(false)`, Nette includerà il loro valore in questi dati.

Quando si chiama `setDisabled()`, il valore del campo viene cancellato. Se si imposta un valore predefinito, è necessario farlo dopo averlo disattivato:

```php
$form->addText('username', 'User name:')
	->setDisabled()
	->setDefaultValue($userName);
```


Controlli personalizzati .[#toc-custom-controls]
================================================

Oltre all'ampia gamma di controlli incorporati nel modulo, è possibile aggiungere controlli personalizzati al modulo come segue:

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

.[note]
Il modulo è un discendente della classe [Container | component-model:#Container] e gli elementi sono discendenti di [Component | component-model:#Component].

Esiste un modo per definire nuovi metodi del modulo per aggiungere elementi personalizzati (ad esempio `$form->addZip()`). Questi sono i cosiddetti metodi di estensione. Lo svantaggio è che i suggerimenti di codice negli editor non funzionano per questi metodi.

```php
use Nette\Forms\Container;

// aggiunge il metodo addZip(string $nome, string $etichetta = 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:');
```


Campi di basso livello .[#toc-low-level-fields]
===============================================

Per aggiungere un elemento al form, non è necessario chiamare `$form->addXyz()`. Gli elementi del modulo possono essere introdotti esclusivamente nei modelli. Questo è utile se, ad esempio, si ha la necessità di generare elementi dinamici:

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

Dopo l'invio, è possibile recuperare i valori:

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

Nel primo parametro si specifica il tipo di elemento (`DataFile` per `type=file`, `DataLine` per gli input a una riga come `text`, `password` o `email` e `DataText` per gli altri). Il secondo parametro corrisponde all'attributo HTML `name`. Se è necessario preservare le chiavi, si può combinare il primo parametro con `DataKeys`. Questo è utile per `select`, `radioList` o `checkboxList`.

`getHttpData()` restituisce un input sanificato. In questo caso, sarà sempre un array di stringhe UTF-8 valide, indipendentemente dall'attaccante inviato dal modulo. È un'alternativa al lavoro diretto con `$_POST` o `$_GET`, se si vogliono ricevere dati sicuri.

Controlli del modulo

Panoramica dei controlli di modulo incorporati.

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

Aggiunge un campo di testo a riga singola (classe TextInput). Se l'utente non compila il campo, restituisce una stringa vuota '', oppure si può usare setNullable() per modificarlo e restituire null.

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

Convalida automaticamente UTF-8, taglia gli spazi bianchi a destra e a sinistra e rimuove le interruzioni di riga che potrebbero essere inviate da un utente malintenzionato.

La lunghezza massima può essere limitata utilizzando setMaxLength(). Il metodo addFilter() consente di modificare il valore inserito dall'utente.

Utilizzando setHtmlType(), è possibile cambiare il carattere dell'elemento di input in search, tel, url, range, month, week, o color. Per altri tipi, come number, email, date, datetime-local e time, esistono metodi separati addInteger, addFloat, addEmail, addDate, addTime e addDateTime, dotati di validazione lato server.

$form->addText('color', 'Choose color:')
	->setHtmlType('color')
	->addRule($form::Pattern, 'invalid value', '[0-9a-f]{6}');

È possibile impostare il cosiddetto valore vuoto per l'elemento, che è qualcosa di simile al valore predefinito, ma se l'utente non lo sovrascrive, restituisce una stringa vuota o null.

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

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

Aggiunge un campo di testo multilinea (classe TextArea). Se l'utente non compila il campo, restituisce una stringa vuota '', oppure si può usare setNullable() per modificarlo e restituire null.

$form->addTextArea('note', 'Note:')
	->addRule($form::MaxLength, 'Your note is way too long', 10000);

Convalida automaticamente UTF-8 e normalizza le interruzioni di riga a \n. A differenza di un campo di input a una riga, non taglia gli spazi bianchi.

La lunghezza massima può essere limitata utilizzando setMaxLength(). Il metodo addFilter() consente di modificare il valore immesso dall'utente. È possibile impostare il cosiddetto valore vuoto utilizzando setEmptyValue().

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

Aggiunge un campo di input per numeri interi (classe TextInput). Restituisce un intero o null se l'utente non inserisce nulla.

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

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

Adds a field for entering a decimal number (TextInput class). Returns either float or null, if the user does not specify anything.

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

Nette e Chrome accettano sia la virgola che il punto come separatore decimale. Affinché anche Firefox accetti la virgola, è necessario impostare la lingua corrispondente nell'attributo HTML lang, direttamente a questo elemento o a qualsiasi elemento padre, ad esempio <html lang="cs">.

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

Aggiunge un campo per l'indirizzo e-mail con controllo di validità (classe TextInput). Se l'utente non compila il campo, restituisce una stringa vuota '', oppure si può usare setNullable() per modificarlo e restituire null.

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

Verifica che il valore sia un indirizzo e-mail valido. Non verifica l'effettiva esistenza del dominio, ma solo la sintassi. Convalida automaticamente UTF-8, taglia gli spazi bianchi a destra e a sinistra.

La lunghezza massima può essere limitata utilizzando setMaxLength(). Il metodo addFilter() consente di modificare il valore inserito dall'utente. È possibile impostare il cosiddetto valore vuoto utilizzando setEmptyValue().

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

Aggiunge il campo password (classe TextInput).

$form->addPassword('password', 'Password:')
	->setRequired()
	->addRule($form::MinLength, 'Password has to be at least %d characters long', 8)
	->addRule($form::Pattern, 'Password must contain a number', '.*[0-9].*');

Quando si invia nuovamente il modulo, l'input sarà vuoto. Convalida automaticamente UTF-8, taglia gli spazi bianchi a destra e a sinistra e rimuove le interruzioni di riga che potrebbero essere inviate da un utente malintenzionato.

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

Aggiunge una casella di controllo (classe Checkbox). Il campo restituisce true o false, a seconda che sia selezionato o meno.

$form->addCheckbox('agree', 'I agree with terms')
	->setRequired('You must agree with our terms');

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

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

$form->addCheckboxList('colors', 'Colors:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);

Si passa l'array di elementi come terzo parametro o con il metodo setItems().

È possibile utilizzare setDisabled(['r', 'g']) per disabilitare singoli elementi.

L'elemento controlla automaticamente che non ci siano state contraffazioni e che gli elementi selezionati siano effettivamente tra quelli proposti e non siano stati disabilitati. Il metodo getRawValue() può essere utilizzato per recuperare gli elementi inviati senza questo importante controllo.

Quando sono impostati dei valori predefiniti, controlla anche che siano uno degli elementi offerti, altrimenti lancia un'eccezione. Questo controllo può essere disattivato con checkDefaultValue(false).

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 un valore invece di una chiave.

$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);

Si passa l'array di elementi come terzo parametro o con il metodo setItems().

È possibile utilizzare setDisabled(['m']) per disabilitare singoli elementi.

L'elemento controlla automaticamente che non ci siano state contraffazioni e che l'elemento selezionato sia effettivamente uno di quelli proposti e non sia stato disabilitato. Il metodo getRawValue() può essere utilizzato per recuperare l'elemento inviato senza questo importante controllo.

Quando il valore predefinito è impostato, controlla anche che sia uno degli elementi offerti, altrimenti lancia un'eccezione. Questo controllo può essere disattivato con checkDefaultValue(false).

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

Aggiunge una casella di selezione (classe SelectBox). Restituisce la chiave dell'elemento selezionato o null se l'utente non ha selezionato nulla. Il metodo getSelectedItem() restituisce un valore invece di una chiave.

$countries = [
	'CZ' => 'Czech republic',
	'SK' => 'Slovakia',
	'GB' => 'United Kingdom',
];

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

Si passa l'array di elementi come terzo parametro o con il metodo setItems(). L'array di elementi può anche essere bidimensionale:

$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];

Per le caselle di selezione, il primo elemento ha spesso un significato speciale, in quanto funge da invito all'azione. Utilizzare il metodo setPrompt() per aggiungere una voce di questo tipo.

$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');

È possibile utilizzare setDisabled(['CZ', 'SK']) per disabilitare singole voci.

L'elemento controlla automaticamente che non ci siano state contraffazioni e che l'elemento selezionato sia effettivamente uno di quelli proposti e non sia stato disabilitato. Il metodo getRawValue() può essere utilizzato per recuperare l'elemento inviato senza questo importante controllo.

Quando il valore predefinito è impostato, controlla anche che sia uno degli elementi offerti, altrimenti lancia un'eccezione. Questo controllo può essere disattivato con checkDefaultValue(false).

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

Aggiunge una casella di selezione a scelta multipla (classe MultiSelectBox). Restituisce l'array di chiavi degli elementi selezionati. Il metodo getSelectedItems() restituisce i valori invece delle chiavi.

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

La matrice di elementi viene passata come terzo parametro o con il metodo setItems(). L'array di elementi può anche essere bidimensionale.

È possibile utilizzare setDisabled(['CZ', 'SK']) per disabilitare singoli elementi.

L'elemento controlla automaticamente che non ci siano state contraffazioni e che gli elementi selezionati siano effettivamente tra quelli proposti e non siano stati disabilitati. Il metodo getRawValue() può essere utilizzato per recuperare gli elementi inviati senza questo importante controllo.

Quando sono impostati dei valori predefiniti, controlla anche che siano uno degli elementi offerti, altrimenti lancia un'eccezione. Questo controllo può essere disattivato con checkDefaultValue(false).

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

Aggiunge il campo di caricamento dei file (classe UploadControl). Restituisce l'oggetto FileUpload, anche se l'utente non ha caricato un file, cosa che può essere scoperta con il metodo FileUpload::hasFile().

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatar must be JPEG, PNG, GIF or WebP')
	->addRule($form::MaxFileSize, 'Maximum size is 1 MB', 1024 * 1024);

Se il file non è stato caricato correttamente, il modulo non è stato inviato con successo e viene visualizzato un errore. Non è quindi necessario controllare il metodo FileUpload::isOk().

Non fidatevi del nome originale del file restituito dal metodo FileUpload::getName(), un client potrebbe inviare un nome di file dannoso con l'intenzione di corrompere o hackerare l'applicazione.

Le regole MimeType e Image rilevano il tipo di file o immagine richiesto in base alla sua firma. L'integrità dell'intero file non viene controllata. È possibile scoprire se un'immagine non è danneggiata, ad esempio provando a caricarla.

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

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

$form->addMultiUpload('files', 'Files:')
	->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);

Se uno dei file non viene caricato correttamente, il modulo non è stato inviato correttamente e viene visualizzato un errore. Non è quindi necessario controllare il metodo FileUpload::isOk().

Non fidatevi dei nomi originali dei file restituiti dal metodo FileUpload::getName(), un client potrebbe inviare un nome di file dannoso con l'intenzione di corrompere o hackerare l'applicazione.

Le regole MimeType e Image rilevano il tipo di file o immagine richiesto in base alla sua firma. L'integrità dell'intero file non viene controllata. È possibile scoprire se un'immagine non è danneggiata, ad esempio provando a caricarla.

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

Per il valore predefinito, accetta o oggetti che implementano la regola DateTimeInterface, una stringa con l'ora o 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 consentita.

$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Per impostazione predefinita, restituisce un oggetto DateTimeImmutable. Utilizzando il metodo setFormat(), è possibile specificare un formato di testo o un timestamp:

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

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

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

Per il valore predefinito, accetta oggetti che implementano DateTimeInterface, una stringa con l'ora o un numero che rappresenta un timestamp UNIX. Solo le informazioni sull'ora di questi input vengono utilizzate; la data viene ignorata. Lo stesso vale per gli argomenti delle regole Min, Max, o Range, che definiscono il tempo minimo e massimo consentito. Se il valore minimo impostato è superiore a quello massimo, viene creato un intervallo di tempo che copre la mezzanotte.

$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);

Per impostazione predefinita, restituisce un oggetto DateTimeImmutable (con data 1 gennaio, anno 1). Utilizzando il metodo setFormat(), è possibile specificare un formato di testo:

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

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

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

Per il valore predefinito, accetta sia oggetti che implementano DateTimeInterface, sia una stringa con l'ora, sia 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 consentita.

$form->addDateTime('datetime', 'Date and Time:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Per impostazione predefinita, restituisce un oggetto DateTimeImmutable. Utilizzando il metodo setFormat(), è possibile specificare un formato di testo o un timestamp:

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

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

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

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

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

Aggiunge un campo nascosto (classe HiddenField).

$form->addHidden('userid');

Utilizzare setNullable() per modificarlo in modo che restituisca null invece di una stringa vuota. Il metodo addFilter() consente di modificare il valore inviato.

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

Aggiunge il pulsante di invio (classe SubmitButton).

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

È possibile avere più di un pulsante di invio nel modulo:

$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');

Per sapere quale di essi è stato cliccato, utilizzare:

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

Se non si desidera convalidare il modulo quando viene premuto un pulsante di invio (come i pulsanti CancelPreview), è possibile disattivarlo con setValidationScope().

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

Aggiunge un pulsante (classe Button) senza funzione di invio. È utile per legare altre funzionalità all'id, ad esempio un'azione JavaScript.

$form->addButton('raise', 'Raise salary')
	->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');

Quando si usano più pulsanti di invio, si può sapere quale è stato cliccato con $form['submit']->isSubmittedBy().

addContainer(string|int $name): Container

Aggiunge un sub-form (classe Container), o un contenitore, che può essere trattato come un form. Ciò significa che si possono usare metodi come setDefaults() o getValues().

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

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

I dati inviati vengono restituiti come struttura multidimensionale:

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

Panoramica delle impostazioni

Per tutti gli elementi si possono richiamare i seguenti metodi (si veda la documentazione dell'API per una panoramica completa):

setDefaultValue($value) imposta il valore predefinito
getValue() ottiene il valore corrente
setOmitted() omettere i valori
setDisabled() disabilitare gli ingressi

Rendering:

setCaption($caption) modifica la didascalia 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) imposta i dati di rendering

Convalida:

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

I seguenti metodi possono essere richiamati per gli elementi addText(), addPassword(), addTextArea(), addEmail(), addInteger():

setNullable() imposta se getValue() restituisce null invece della stringa vuota
setEmptyValue($value) imposta il valore speciale che viene trattato come stringa vuota
setMaxLength($length) imposta il numero massimo di caratteri consentiti
addFilter($filter) modificare i valori di input

Valori omessi

Se non si è interessati al valore inserito dall'utente, si può usare setOmitted() per ometterlo dal risultato fornito dal metodo $form->getValues​() o passato ai gestori. Questo è adatto per varie password di verifica, campi antispam, ecc.

$form->addPassword('passwordVerify', 'Password again:')
	->setRequired('Fill your password again to check for typo')
	->addRule($form::Equal, 'Password mismatch', $form['password'])
	->setOmitted();

Disabilitazione degli ingressi

Per disabilitare un input, si può chiamare setDisabled(). Questo campo non può essere modificato dall'utente.

$form->addText('username', 'User name:')
	->setDisabled();

I campi disabilitati non vengono inviati dal browser al server, quindi non sono presenti nei dati restituiti dalla funzione $form->getValues(). Tuttavia, se si imposta setOmitted(false), Nette includerà il loro valore in questi dati.

Quando si chiama setDisabled(), il valore del campo viene cancellato. Se si imposta un valore predefinito, è necessario farlo dopo averlo disattivato:

$form->addText('username', 'User name:')
	->setDisabled()
	->setDefaultValue($userName);

Controlli personalizzati

Oltre all'ampia gamma di controlli incorporati nel modulo, è possibile aggiungere controlli personalizzati al modulo come segue:

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

Il modulo è un discendente della classe Container e gli elementi sono discendenti di Component.

Esiste un modo per definire nuovi metodi del modulo per aggiungere elementi personalizzati (ad esempio $form->addZip()). Questi sono i cosiddetti metodi di estensione. Lo svantaggio è che i suggerimenti di codice negli editor non funzionano per questi metodi.

use Nette\Forms\Container;

// aggiunge il metodo addZip(string $nome, string $etichetta = 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:');

Campi di basso livello

Per aggiungere un elemento al form, non è necessario chiamare $form->addXyz(). Gli elementi del modulo possono essere introdotti esclusivamente nei modelli. Questo è utile se, ad esempio, si ha la necessità di generare elementi dinamici:

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

Dopo l'invio, è possibile recuperare i valori:

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

Nel primo parametro si specifica il tipo di elemento (DataFile per type=file, DataLine per gli input a una riga come text, password o email e DataText per gli altri). Il secondo parametro corrisponde all'attributo HTML name. Se è necessario preservare le chiavi, si può combinare il primo parametro con DataKeys. Questo è utile per select, radioList o checkboxList.

getHttpData() restituisce un input sanificato. In questo caso, sarà sempre un array di stringhe UTF-8 valide, indipendentemente dall'attaccante inviato dal modulo. È un'alternativa al lavoro diretto con $_POST o $_GET, se si vogliono ricevere dati sicuri.