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