Controlli del modulo

Panoramica dei controlli di modulo incorporati.

addText (string|int $name, $label=null, $cols, ?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 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.

È possibile cambiare il carattere visivo di un campo di testo in tipi come search, tel, o url usando setHtmlType(), come si vede nelle specifiche. Ricordare che la modifica del tipo è solo visiva e non svolge funzioni di validazione. Per il tipo url, è opportuno aggiungere una regola URL specifica.

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 da tutti i browser.

È 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]);

L'elemento viene reso come <input type="numeric">. Utilizzando il metodo setHtmlType(), si può cambiare il tipo in range per la visualizzazione come cursore, oppure in text se si preferisce un campo di testo standard senza il comportamento speciale di numeric.

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 il browser Chrome accettano sia una virgola che un punto come separatori decimali. Per rendere disponibile questa funzionalità in Firefox, si consiglia di impostare l'attributo lang per un elemento specifico o per l'intera pagina, ad esempio, <html lang="cs">.

addEmail (string|int $name, $label=null, int $maxLength=255): 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, $cols, ?int $maxLength=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).

Se si invia un modulo con il metodo GET, è possibile scegliere un metodo di trasferimento dei dati più compatto, che consente di risparmiare sulle dimensioni della stringa di query. Questo metodo si attiva impostando l'attributo HTML del modulo:

$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 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, ?int $size=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.

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, ?int $size=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.

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.

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.

Sebbene l'elemento sia nascosto, è importante rendersi conto che il suo valore può comunque essere modificato o falsificato da un utente malintenzionato. Verificare e convalidare sempre accuratamente tutti i valori ricevuti sul lato server per evitare rischi di sicurezza associati alla manipolazione dei dati.

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 Cancel o Preview), è 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

Gli ingressi possono essere disabilitati utilizzando setDisabled(). Un ingresso disabilitato non può essere modificato dall'utente.

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

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

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

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

Un'alternativa agli input disabilitati sono i campi con l'attributo HTML readonly, che vengono inviati al server dal browser. Sebbene il campo sia solo leggibile, è importante rendersi conto che il suo valore può comunque essere modificato o falsificato da un utente malintenzionato.

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.