Elemente de formular

Prezentare generală a elementelor de formular standard.

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

Adaugă un câmp text pe o singură linie (clasa TextInput). Dacă utilizatorul nu completează câmpul, returnează un șir gol '', sau folosind setNullable() se poate specifica să returneze null.

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

Validează automat UTF-8, elimină spațiile de la început și sfârșit și elimină sfârșiturile de linie pe care un atacator le-ar putea trimite. Parametrul $cols este depreciat și nu este utilizat.

Lungimea maximă poate fi limitată folosind setMaxLength(). Modificarea valorii introduse de utilizator este posibilă prin addFilter().

Folosind setHtmlType() se poate schimba caracterul vizual al câmpului text la tipuri precum search, tel sau url vezi specificație. Rețineți că schimbarea tipului este doar vizuală și nu înlocuiește funcția de validare. Pentru tipul url este recomandat să se adauge o regulă de validare specifică URL.

Pentru alte tipuri de intrări, cum ar fi number, range, email, date, datetime-local, time și color, utilizați metode specializate precum addInteger, addFloat, addEmail addDate, addTime, addDateTime și addColor, care asigură validarea pe server. Tipurile month și week nu sunt încă pe deplin suportate în toate browserele.

Elementului i se poate seta așa-numita empty-value, care este ceva asemănător valorii implicite, dar dacă utilizatorul nu o schimbă, elementul returnează un șir gol sau null.

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

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

Adaugă un câmp pentru introducerea textului multilinie (clasa TextArea). Dacă utilizatorul nu completează câmpul, returnează un șir gol '', sau folosind setNullable() se poate specifica să returneze null.

$form->addTextArea('note', 'Notă:')
	->addRule($form::MaxLength, 'Nota este prea lungă', 10000);

Validează automat UTF-8 și normalizează separatorii de linie la \n. Spre deosebire de câmpul de intrare pe o singură linie, nu are loc nicio eliminare a spațiilor.

Lungimea maximă poate fi limitată folosind setMaxLength(). Modificarea valorii introduse de utilizator este posibilă prin addFilter(). Se poate seta așa-numita empty-value folosind setEmptyValue().

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

Adaugă un câmp pentru introducerea unui număr întreg (clasa TextInput). Returnează fie un integer, fie null, dacă utilizatorul nu introduce nimic.

$form->addInteger('year', 'An:')
	->addRule($form::Range, 'Anul trebuie să fie în intervalul de la %d la %d.', [1900, 2023]);

Elementul se randează ca <input type="number">. Folosind metoda setHtmlType() se poate schimba tipul la range pentru afișare sub formă de glisor, sau la text, dacă preferați un câmp text standard fără comportamentul special al tipului number.

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

Adaugă un câmp pentru introducerea unui număr zecimal (clasa TextInput). Returnează fie un float, fie null, dacă utilizatorul nu introduce nimic.

$form->addFloat('level', 'Nivel:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Nivelul trebuie să fie în intervalul de la %d la %d.', [0, 100]);

Nette și browserul Chrome acceptă atât virgula, cât și punctul ca separator zecimal. Pentru ca această funcționalitate să fie disponibilă și în Firefox, se recomandă setarea atributului lang fie pentru elementul respectiv, fie pentru întreaga pagină, de exemplu <html lang="ro">.

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

Adaugă un câmp pentru introducerea unei adrese de e-mail (clasa TextInput). Dacă utilizatorul nu completează câmpul, returnează un șir gol '', sau folosind setNullable() se poate specifica să returneze null.

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

Verifică dacă valoarea este o adresă de e-mail validă. Nu se verifică dacă domeniul există efectiv, se verifică doar sintaxa. Validează automat UTF-8, elimină spațiile de la început și sfârșit.

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

Adaugă un câmp pentru introducerea parolei (clasa TextInput). Parametrul $cols este depreciat și nu este utilizat.

$form->addPassword('password', 'Parolă:')
	->setRequired()
	->addRule($form::MinLength, 'Parola trebuie să aibă cel puțin %d caractere', 8)
	->addRule($form::Pattern, 'Trebuie să conțină o cifră', '.*[0-9].*');

La reafișarea formularului, câmpul va fi gol. Validează automat UTF-8, elimină spațiile de la început și sfârșit și elimină sfârșiturile de linie pe care un atacator le-ar putea trimite.

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

Adaugă o căsuță de bifat (clasa Checkbox). Returnează valoarea true sau false, în funcție de dacă este bifată.

$form->addCheckbox('agree', 'Sunt de acord cu termenii')
	->setRequired('Este necesar să fiți de acord cu termenii');

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

Adaugă căsuțe de bifat pentru selectarea mai multor elemente (clasa CheckboxList). Returnează un array al cheilor elementelor selectate. Metoda getSelectedItems() returnează valorile în loc de chei.

$form->addCheckboxList('colors', 'Culori:', [
	'r' => 'roșu',
	'g' => 'verde',
	'b' => 'albastru',
]);

Array-ul de elemente oferite îl transmitem ca al treilea parametru sau prin metoda setItems().

Folosind setDisabled(['r', 'g']) se pot dezactiva elemente individuale.

Elementul verifică automat că nu a avut loc o falsificare și că elementele selectate sunt într-adevăr unele dintre cele oferite și nu au fost dezactivate. Prin metoda getRawValue() se pot obține elementele trimise fără această verificare importantă.

La setarea elementelor selectate implicit, verifică de asemenea că acestea sunt unele dintre cele oferite, altfel aruncă o excepție. Această verificare poate fi dezactivată folosind checkDefaultValue(false).

Dacă trimiteți formularul prin metoda GET, puteți alege un mod mai compact de transmitere a datelor, care economisește dimensiunea query string-ului. Se activează prin setarea atributului HTML al formularului:

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

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

Adaugă butoane radio (clasa RadioList). Returnează cheia elementului selectat, sau null, dacă utilizatorul nu a selectat nimic. Metoda getSelectedItem() returnează valoarea în loc de cheie.

$sex = [
	'm' => 'bărbat',
	'f' => 'femeie',
];
$form->addRadioList('gender', 'Sex:', $sex);

Array-ul de elemente oferite îl transmitem ca al treilea parametru sau prin metoda setItems().

Folosind setDisabled(['m', 'f']) se pot dezactiva elemente individuale.

Elementul verifică automat că nu a avut loc o falsificare și că elementul selectat este într-adevăr unul dintre cele oferite și nu a fost dezactivat. Prin metoda getRawValue() se poate obține elementul trimis fără această verificare importantă.

La setarea elementului selectat implicit, verifică de asemenea că acesta este unul dintre cele oferite, altfel aruncă o excepție. Această verificare poate fi dezactivată folosind checkDefaultValue(false).

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

Adaugă un select box (clasa SelectBox). Returnează cheia elementului selectat, sau null, dacă utilizatorul nu a selectat nimic. Metoda getSelectedItem() returnează valoarea în loc de cheie.

$countries = [
	'RO' => 'România',
	'MD' => 'Moldova',
	'GB' => 'Marea Britanie',
];

$form->addSelect('country', 'Țara:', $countries)
	->setDefaultValue('RO');

Array-ul de elemente oferite îl transmitem ca al treilea parametru sau prin metoda setItems(). Elementele pot fi și un array bidimensional:

$countries = [
	'Europe' => [
		'RO' => 'România',
		'MD' => 'Moldova',
		'GB' => 'Marea Britanie',
	],
	'CA' => 'Canada',
	'US' => 'SUA',
	'?'  => 'altă',
];

La select box-uri, adesea primul element are o semnificație specială, servește ca îndemn la acțiune. Pentru adăugarea unui astfel de element servește metoda setPrompt().

$form->addSelect('country', 'Țara:', $countries)
	->setPrompt('Alegeți țara');

Folosind setDisabled(['RO', 'MD']) se pot dezactiva elemente individuale.

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

Adaugă un select box pentru selectarea mai multor elemente (clasa MultiSelectBox). Returnează un array al cheilor elementelor selectate. Metoda getSelectedItems() returnează valorile în loc de chei.

$form->addMultiSelect('countries', 'Țări:', $countries);

Array-ul de elemente oferite îl transmitem ca al treilea parametru sau prin metoda setItems(). Elementele pot fi și un array bidimensional.

Folosind setDisabled(['RO', 'MD']) se pot dezactiva elemente individuale.

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

Adaugă un câmp pentru încărcarea fișierului (clasa UploadControl). Returnează un obiect FileUpload, chiar și în cazul în care utilizatorul nu a trimis niciun fișier, ceea ce se poate verifica prin metoda FileUpload::hasFile().

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatarul trebuie să fie JPEG, PNG, GIF, WebP sau AVIF.')
	->addRule($form::MaxFileSize, 'Dimensiunea maximă este 1 MB.', 1024 * 1024);

Dacă fișierul nu reușește să se încarce corect, formularul nu este trimis cu succes și se afișează o eroare. Adică, la trimiterea cu succes nu este nevoie să se verifice metoda FileUpload::isOk().

Nu aveți niciodată încredere în numele original al fișierului returnat de metoda FileUpload::getName(), clientul ar fi putut trimite un nume de fișier malițios cu intenția de a deteriora sau hackui aplicația dvs.

Regulile MimeType și Image detectează tipul solicitat pe baza semnăturii fișierului și nu verifică integritatea acestuia. Dacă imaginea nu este deteriorată se poate verifica, de exemplu, prin încercarea de a o încărca.

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

Adaugă un câmp pentru încărcarea mai multor fișiere simultan (clasa UploadControl). Returnează un array de obiecte FileUpload. Metoda FileUpload::hasFile() pentru fiecare dintre ele va returna true.

$form->addMultiUpload('files', 'Fișiere:')
	->addRule($form::MaxLength, 'Maxim se pot încărca %d fișiere', 10);

Dacă vreun fișier nu reușește să se încarce corect, formularul nu este trimis cu succes și se afișează o eroare. Adică, la trimiterea cu succes nu este nevoie să se verifice metoda FileUpload::isOk().

Nu aveți niciodată încredere în numele originale ale fișiierelor returnate de metoda FileUpload::getName(), clientul ar fi putut trimite un nume de fișier malițios cu intenția de a deteriora sau hackui aplicația dvs.

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

Adaugă un câmp care permite utilizatorului să introducă ușor o dată formată din an, lună și zi (clasa DateTimeControl).

Ca valoare implicită acceptă fie obiecte care implementează interfața DateTimeInterface, un șir cu timpul, fie un număr reprezentând timestamp UNIX. Același lucru este valabil și pentru argumentele regulilor Min, Max sau Range, care definesc data minimă și maximă permisă.

$form->addDate('date', 'Data:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'Data trebuie să fie cu cel puțin o lună în urmă.', new DateTime('-1 month'));

Standard returnează un obiect DateTimeImmutable, prin metoda setFormat() puteți specifica formatul text sau timestamp:

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

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

Adaugă un câmp care permite utilizatorului să introducă ușor un timp format din ore, minute și opțional secunde (clasa DateTimeControl).

Ca valoare implicită acceptă fie obiecte care implementează interfața DateTimeInterface, un șir cu timpul, fie un număr reprezentând timestamp UNIX. Din aceste intrări este utilizată doar informația de timp, data este ignorată. Același lucru este valabil și pentru argumentele regulilor Min, Max sau Range, care definesc timpul minim și maxim permis. Dacă valoarea minimă setată este mai mare decât cea maximă, se creează un interval de timp care depășește miezul nopții.

$form->addTime('time', 'Ora:', withSeconds: true)
	->addRule($form::Range, 'Ora trebuie să fie în intervalul de la %d la %d.', ['12:30', '13:30']);

Standard returnează un obiect DateTimeImmutable (cu data 1 ianuarie anul 1), prin metoda setFormat() puteți specifica formatul text:

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

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

Adaugă un câmp care permite utilizatorului să introducă ușor data și ora formate din an, lună, zi, ore, minute și opțional secunde (clasa DateTimeControl).

$form->addDateTime('datetime', 'Data și ora:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'Data trebuie să fie cu cel puțin o lună în urmă.', new DateTime('-1 month'));

Standard returnează un obiect DateTimeImmutable, prin metoda setFormat() puteți specifica formatul text sau timestamp:

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

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

Adaugă un câmp pentru selectarea culorii (clasa ColorPicker). Culoarea este un șir în formatul #rrggbb. Dacă utilizatorul nu face nicio selecție, se returnează culoarea neagră #000000.

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

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

Adaugă un câmp ascuns (clasa HiddenField).

$form->addHidden('userid');

Folosind setNullable() se poate seta să returneze null în loc de șir gol. Modificarea valorii trimise este posibilă prin addFilter().

Deși elementul este ascuns, este important să rețineți că valoarea poate fi totuși modificată sau falsificată de un atacator. Verificați și validați întotdeauna cu atenție toate valorile primite pe partea serverului pentru a preveni riscurile de securitate asociate cu manipularea datelor.

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

Adaugă un buton de trimitere (clasa SubmitButton).

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

În formular este posibil să aveți și mai multe butoane de trimitere:

$form->addSubmit('register', 'Înregistrează-te');
$form->addSubmit('cancel', 'Anulează');

Pentru a afla pe care dintre ele s-a făcut clic, utilizați:

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

Dacă nu doriți să validați întregul formular la apăsarea butonului (de exemplu, la butoanele Anulează sau Previzualizare), utilizați setValidationScope().

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

Adaugă un buton (clasa Button), care nu are funcție de trimitere. Poate fi deci utilizat pentru o altă funcție, de ex. apelarea unei funcții JavaScript la clic.

$form->addButton('raise', 'Mărește salariul')
	->setHtmlAttribute('onclick', 'raiseSalary()');

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

Adaugă un buton de trimitere sub formă de imagine (clasa ImageButton).

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

La utilizarea mai multor butoane de trimitere se poate afla pe care s-a făcut clic folosind $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Adaugă un subformular (clasa Container), adică un container, în care se pot adăuga alte elemente în același mod în care le adăugăm în formular. Funcționează și metodele setDefaults() sau getValues().

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

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

Datele trimise le returnează apoi ca o structură multidimensională:

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

Prezentare generală a setărilor

La toate elementele putem apela următoarele metode (prezentare completă în documentația API):

`setDefaultValue($value)`	setează valoarea implicită
`getValue()`	obține valoarea curentă
`setOmitted()`	Omiterea valorii
`setDisabled()`	Dezactivarea elementelor

Randare:

`setCaption($caption)`	schimbă eticheta elementului
`setTranslator($translator)`	setează traducătorul
`setHtmlAttribute($name, $value)`	setează atributul HTML al elementului
`setHtmlId($id)`	setează atributul HTML `id`
`setHtmlType($type)`	setează atributul HTML `type`
`setHtmlName($name)`	setează atributul HTML `name`
`setOption($key, $value)`	opțiuni de randare

Validare:

`setRequired()`	element obligatoriu
`addRule()`	setarea regulii de validare
`addCondition()`, `addConditionOn()`	setează condiția de validare
`addError($message)`	transmiterea mesajului de eroare

La elementele addText(), addPassword(), addTextArea(), addEmail(), addInteger() se pot apela următoarele metode:

`setNullable()`	setează dacă getValue() va returna `null` în loc de șir gol
`setEmptyValue($value)`	setează o valoare specială care este considerată șir gol
`setMaxLength($length)`	setează numărul maxim de caractere permise
`addFilter($filter)`	modificarea intrării

Omiterea valorii

Dacă valoarea completată de utilizator nu ne interesează, o putem omite din rezultatul metodei $form->getValues() sau din datele transmise handlerilor folosind setOmitted(). Acest lucru este util pentru diverse parole de verificare, elemente antispam etc.

$form->addPassword('passwordVerify', 'Parola pentru verificare:')
	->setRequired('Vă rugăm introduceți parola încă o dată pentru verificare')
	->addRule($form::Equal, 'Parolele nu se potrivesc', $form['password'])
	->setOmitted();

Dezactivarea elementelor

Elementele pot fi dezactivate folosind setDisabled(). Un astfel de element nu poate fi editat de utilizator.

$form->addText('username', 'Nume utilizator:')
	->setDisabled();

Elementele dezactivate nu sunt trimise deloc de browser către server, deci nu le veți găsi nici în datele returnate de funcția $form->getValues(). Dacă însă setați setOmitted(false), Nette va include în aceste date valoarea lor implicită.

La apelarea setDisabled(), din motive de securitate se șterge valoarea elementului. Dacă setați o valoare implicită, este necesar să o faceți după dezactivarea acestuia:

$form->addText('username', 'Nume utilizator:')
	->setDisabled()
	->setDefaultValue($userName);

O alternativă la elementele dezactivate sunt elementele cu atributul HTML readonly, pe care browserul le trimite la server. Deși elementul este doar pentru citire, este important să rețineți că valoarea sa poate fi totuși modificată sau falsificată de un atacator.

Elemente personalizate

Pe lângă gama largă de elemente de formular încorporate, puteți adăuga elemente personalizate în formular în acest mod:

$form->addComponent(new DateInput('Data:'), 'date');
// sintaxă alternativă: $form['date'] = new DateInput('Data:');

Formularul este un descendent al clasei Container, iar elementele individuale sunt descendenți ai Component.

Există o modalitate de a defini noi metode ale formularului care servesc la adăugarea elementelor personalizate (de ex. $form->addZip()). Este vorba de așa-numitele extension methods. Dezavantajul este că sugestiile din editori nu vor funcționa pentru ele.

use Nette\Forms\Container;

// adăugăm metoda addZip(string $name, ?string $label = null)
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'Cel puțin 5 cifre', '[0-9]{5}');
});

// utilizare
$form->addZip('zip', 'Cod poștal:');

Elemente de nivel scăzut

Se pot utiliza și elemente pe care le scriem doar în șablon și nu le adăugăm în formular prin una dintre metodele $form->addXyz(). De exemplu, când afișăm înregistrări din baza de date și nu știm dinainte câte vor fi și ce ID-uri vor avea, și dorim să afișăm la fiecare rând un checkbox sau un radio button, este suficient să îl codăm în șablon:

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

Și după trimitere aflăm valoarea:

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

unde primul parametru este tipul elementului (DataFile pentru type=file, DataLine pentru intrări pe o singură linie precum text, password, email etc. și DataText pentru toate celelalte) iar al doilea parametru sel[] corespunde atributului HTML name. Tipul elementului îl putem combina cu valoarea DataKeys, care păstrează cheile elementelor. Acest lucru este util în special pentru select, radioList și checkboxList.

Esențial este că getHttpData() returnează o valoare sanitarizată, în acest caz va fi întotdeauna un array de șiruri UTF-8 valide, indiferent ce ar încerca un atacator să strecoare serverului. Este o analogie a lucrului direct cu $_POST sau $_GET, dar cu diferența esențială că returnează întotdeauna date curate, așa cum sunteți obișnuiți la elementele standard ale formularelor Nette.