Controale de formular

Prezentare generală a controalelor de formular încorporate.

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

Adaugă un câmp de text cu o singură linie (clasa TextInput). Dacă utilizatorul nu completează câmpul, acesta returnează un șir de caractere gol '', sau se poate folosi setNullable() pentru a schimba acest câmp și a returna null.

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

Validează automat UTF-8, taie spațiile albe din stânga și din dreapta și elimină întreruperile de linie care ar putea fi trimise de un atacator.

Lungimea maximă poate fi limitată folosind setMaxLength(). AddFilter() vă permite să modificați valoarea introdusă de utilizator.

Puteți schimba caracterul vizual al unui câmp de text în tipuri precum search, tel, sau url folosind setHtmlType(), așa cum se vede în specificație. Rețineți că schimbarea tipului este doar vizuală și nu îndeplinește funcții de validare. Pentru tipul url, este oportun să se adauge o regulă URL specifică.

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

Pentru element se poate seta așa-numita “empty-value”, care este ceva de genul valorii implicite, dar, dacă utilizatorul nu o suprascrie, returnează un șir de caractere gol sau null.

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

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

Adaugă un câmp de text cu mai multe linii (clasa TextArea). Dacă utilizatorul nu completează câmpul, acesta returnează un șir de caractere gol '', sau se poate folosi setNullable() pentru a schimba acest câmp și a returna null.

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

Validează automat UTF-8 și normalizează întreruperile de linie la \n. Spre deosebire de un câmp de introducere a textului pe o singură linie, nu taie spațiile albe.

Lungimea maximă poate fi limitată folosind setMaxLength(). AddFilter() vă permite să modificați valoarea introdusă de utilizator. Puteți seta așa-numita valoare goală folosind setEmptyValue().

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

Adaugă un câmp de intrare pentru numere întregi (clasa TextInput). Returnează fie un număr întreg, fie null dacă utilizatorul nu introduce nimic.

$form->addInteger('an', 'Anul:')
	->addRule($form::Range, 'Anul trebuie să fie cuprins între %d și %d.', [1900, 2023 |1900, 2023]);

Elementul este redat ca <input type="numeric">. Prin utilizarea metodei setHtmlType(), puteți schimba tipul la range pentru afișarea ca cursor sau la text dacă preferați un câmp text standard fără comportamentul special al 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, 'Nivelul trebuie să fie cuprins între %d și %d.', [0, 100 |0, 100]);

Nette și browserul Chrome acceptă atât o virgulă, cât și un punct ca separatori de zecimale. Pentru ca această funcționalitate să fie disponibilă în Firefox, se recomandă să setați atributul lang fie pentru elementul specific, fie pentru întreaga pagină, de exemplu, <html lang="cs">.

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

Adaugă un câmp de adresă de e-mail cu verificare a validității (clasa TextInput). Dacă utilizatorul nu completează câmpul, acesta returnează un șir de caractere gol '', sau se poate folosi setNullable() pentru a schimba acest câmp și a returna null.

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

Verifică dacă valoarea este o adresă de e-mail validă. Nu se verifică dacă domeniul există cu adevărat, ci doar sintaxa. Validează automat UTF-8, taie spațiile albe din stânga și din dreapta.

Lungimea maximă poate fi limitată folosind setMaxLength(). AddFilter() vă permite să modificați valoarea introdusă de utilizator. Puteți seta așa-numita “valoare goală” folosind setEmptyValue().

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

Adaugă câmpul de parolă (clasa 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].*');

La retrimiterea formularului, câmpul de intrare va fi gol. Validează automat UTF-8, taie spațiile albe din stânga și din dreapta și elimină întreruperile de linie care ar putea fi trimise de un atacator.

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

Adaugă o casetă de selectare (clasa Checkbox). Câmpul returnează fie true, fie false, în funcție de faptul dacă este bifat sau nu.

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

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

Adaugă o listă de căsuțe de bifat pentru selectarea mai multor elemente (clasa CheckboxList). Returnează matricea de chei a elementelor selectate. Metoda getSelectedItems() returnează valori în loc de chei.

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

Trecem matricea de elemente ca al treilea parametru sau prin metoda setItems().

Puteți utiliza setDisabled(['r', 'g']) pentru a dezactiva elemente individuale.

Elementul verifică în mod automat dacă nu a existat nicio falsificare și dacă elementele selectate sunt într-adevăr unul dintre cele oferite și nu au fost dezactivate. Metoda getRawValue() poate fi utilizată pentru a prelua elementele trimise fără această verificare importantă.

În cazul în care sunt stabilite valori implicite, se verifică, de asemenea, dacă acestea sunt unul dintre elementele oferite, în caz contrar se aruncă o excepție. Această verificare poate fi dezactivată cu checkDefaultValue(false).

Dacă trimiteți un formular utilizând metoda GET, puteți alege o metodă de transfer de date mai compactă care să economisească dimensiunea șirului de interogare. Aceasta 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ă o valoare în loc de o cheie.

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

Trecem matricea de elemente ca al treilea parametru, sau prin metoda setItems().

Puteți utiliza setDisabled(['m']) pentru a dezactiva elemente individuale.

Elementul verifică automat dacă nu a existat nicio falsificare și dacă elementul selectat este de fapt unul dintre cele oferite și nu a fost dezactivat. Metoda getRawValue() poate fi utilizată pentru a prelua elementul propus fără această verificare importantă.

În cazul în care este stabilită o valoare implicită, se verifică, de asemenea, dacă este unul dintre elementele oferite, în caz contrar se aruncă o excepție. Această verificare poate fi dezactivată cu checkDefaultValue(false).

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

Adaugă caseta de selectare (clasa SelectBox). Returnează cheia elementului selectat sau null dacă utilizatorul nu a selectat nimic. Metoda getSelectedItem() returnează o valoare în loc de o cheie.

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

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

Trecem matricea de elemente ca al treilea parametru, sau prin metoda setItems(). Rețeaua de elemente poate fi, de asemenea, bidimensională:

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

În cazul căsuțelor de selectare, primul element are adesea o semnificație specială, servind ca un apel la acțiune. Utilizați metoda setPrompt() pentru a adăuga o astfel de intrare.

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

Puteți utiliza setDisabled(['CZ', 'SK']) pentru a dezactiva elemente individuale.

Elementul verifică în mod automat dacă nu a existat nicio falsificare și dacă elementul selectat este într-adevăr unul dintre cele oferite și nu a fost dezactivat. Metoda getRawValue() poate fi utilizată pentru a prelua elementul propus fără această verificare importantă.

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

Adaugă caseta de selectare a mai multor opțiuni (clasa MultiSelectBox). Returnează matricea de chei a elementelor selectate. Metoda getSelectedItems() returnează valori în loc de chei.

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

Trecem matricea de elemente ca al treilea parametru sau prin metoda setItems(). Rețeaua de elemente poate fi, de asemenea, bidimensională.

Puteți utiliza setDisabled(['CZ', 'SK']) pentru a dezactiva elemente individuale.

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

Adaugă câmpul de încărcare a fișierelor (clasa UploadControl). Returnează obiectul FileUpload, chiar dacă utilizatorul nu a încărcat un fișier, lucru care poate fi aflat prin metoda 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);

Dacă fișierul nu a fost încărcat corect, formularul nu a fost trimis cu succes și se afișează o eroare. Adică nu este necesar să se verifice metoda FileUpload::isOk().

Nu vă încredeți în numele original al fișierului returnat de metoda FileUpload::getName(), un client ar putea trimite un nume de fișier malițios cu intenția de a vă corupe sau de a vă pirata aplicația.

Regulile MimeType și Image detectează tipul necesar de fișier sau imagine prin semnătura acestuia. Integritatea întregului fișier nu este verificată. Puteți afla dacă o imagine nu este coruptă, de exemplu, încercând să o încărcați.

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

Adaugă câmpul de încărcare a mai multor fișiere (clasa UploadControl). Returnează o matrice de obiecte FileUpload. Metoda FileUpload::hasFile() va returna true pentru fiecare dintre ele.

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

Dacă unul dintre fișiere nu reușește să fie încărcat corect, formularul nu a fost trimis cu succes și se afișează o eroare. Adică nu este necesar să verificați metoda FileUpload::isOk().

Nu vă încredeți în numele de fișier original returnat de metoda FileUpload::getName(), un client ar putea trimite un nume de fișier malițios cu intenția de a vă corupe sau de a vă pirata aplicația.

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

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

Pentru valoarea implicită, acceptă fie obiecte care implementează DateTimeInterface, fie un șir de caractere cu ora, fie un număr reprezentând un timestamp UNIX. Același lucru este valabil și pentru argumentele regulilor Min, Max sau Range, care definesc data minimă și maximă admisă.

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

În mod implicit, returnează un obiect DateTimeImmutable. Cu ajutorul metodei setFormat(), puteți specifica un format de text sau un timestamp:

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

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

Adaugă un câmp care permite utilizatorului să introducă cu ușurință ora constând în ore, minute și, opțional, secunde (clasa DateTimeControl).

Pentru valoarea implicită, acceptă fie obiecte care implementează DateTimeInterface, fie un șir de caractere cu ora, fie un număr reprezentând un timestamp UNIX. Se utilizează numai informațiile de timp din aceste intrări; data este ignorată. Același lucru este valabil și pentru argumentele de regulă Min, Max sau Range, care definesc timpul minim și maxim admis. Dacă valoarea minimă setată este mai mare decât cea maximă, se creează un interval de timp care se întinde până la miezul nopții.

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

În mod implicit, se returnează un obiect DateTimeImmutable (cu data de 1 ianuarie, anul 1). Cu ajutorul metodei setFormat(), puteți specifica un format de text:

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

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

Adaugă un câmp care permite utilizatorului să introducă cu ușurință atât data, cât și ora, constând în an, lună, zi, ore, minute și, opțional, secunde (clasa DateTimeControl).

$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'));

În mod implicit, returnează un obiect DateTimeImmutable. Cu ajutorul metodei setFormat(), puteți specifica un format de text sau un timestamp:

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

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

Adaugă un câmp de selecție a culorilor (clasa ColorPicker). Culoarea este un șir de caractere în formatul #rrggbb. Dacă utilizatorul nu face o selecție, culoarea implicită returnată este negru #000000.

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

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

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

$form->addHidden('userid');

Folosiți setNullable() pentru a-l schimba pentru a returna null în loc de un șir gol. AddFilter() vă permite să modificați valoarea trimisă.

Deși elementul este ascuns, este important de realizat că valoarea sa poate fi modificată sau falsificată de un atacator. Întotdeauna verificați și validați temeinic toate valorile primite pe partea serverului pentru a preveni riscurile de securitate asociate cu manipularea datelor.

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

Adaugă butonul de trimitere (clasa SubmitButton).

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

Este posibil să existe mai mult de un buton de trimitere în formular:

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

Pentru a afla care dintre ele a fost apăsat, utilizați:

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

Dacă nu doriți să validați formularul atunci când este apăsat un buton de trimitere (cum ar fi butoanele Cancel sau Preview), puteți dezactiva acest lucru cu setValidationScope().

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

Adaugă un buton (clasa Button) fără funcția de trimitere. Este util pentru a lega o altă funcționalitate la id, de exemplu o acțiune JavaScript.

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

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

Adaugă un buton de trimitere sub forma unei imagini (clasa ImageButton).

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

Atunci când se utilizează mai multe butoane de trimitere, puteți afla care dintre ele a fost apăsat cu ajutorul funcției $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Adaugă un subformular (clasa Container) sau un container, care poate fi tratat la fel ca un formular. Aceasta înseamnă că puteți utiliza metode precum setDefaults() sau 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:');

Datele trimise sunt apoi returnate sub forma unei structuri multidimensionale:

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

Prezentare generală a setărilor

Pentru toate elementele putem apela următoarele metode (consultați documentația API pentru o prezentare completă):

`setDefaultValue($value)`	stabilește valoarea implicită
`getValue()`	obține valoarea curentă
`setOmitted()`	valori omise
`setDisabled()`	dezactivarea intrărilor

Renderizare:

`setCaption($caption)`	modificarea legendei 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)`	stabilește atributul HTML `name`
`setOption($key, $value)`	stabilește datele de redare

Validare:

`setRequired()`	câmp obligatoriu
`addRule()`	setează regula de validare
`addCondition()`, `addConditionOn()`	setați condiția de validare
`addError($message)`	transmiterea mesajului de eroare

Următoarele metode pot fi apelate pentru elementele addText(), addPassword(), addTextArea(), addEmail(), addInteger():

`setNullable()`	stabilește dacă getValue() returnează `null` în loc de un șir de caractere gol.
`setEmptyValue($value)`	stabilește valoarea specială care este tratată ca șir de caractere gol
`setMaxLength($length)`	stabilește numărul maxim de caractere permise
`addFilter($filter)`	modificarea valorilor de intrare

Valori omise

Dacă nu vă interesează valoarea introdusă de utilizator, putem folosi setOmitted() pentru a o omite din rezultatul furnizat de metoda $form->getValues() sau transmis către gestionari. Acest lucru este potrivit pentru diverse parole de verificare, câmpuri antispam etc.

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

Dezactivarea intrărilor

Intrările pot fi dezactivate folosind setDisabled(). O intrare dezactivată nu poate fi editată de către utilizator.

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

Intrările dezactivate nu sunt trimise la server de către browser, deci nu le veți găsi în datele returnate de funcția $form->getValues(). Cu toate acestea, dacă setați setOmitted(false), Nette va include valoarea lor implicită în aceste date.

Când este apelată setDisabled(), valoarea intrării este ștearsă din motive de securitate. Dacă setați o valoare implicită, este necesar să faceți acest lucru după dezactivarea acesteia:

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

O alternativă la intrările dezactivate sunt câmpurile cu atributul HTML readonly, care sunt trimise la server de către browser. Deși câmpul este doar lizibil, este important de realizat că valoarea sa poate fi în continuare modificată sau falsificată de un atacator.

Controale personalizate

Pe lângă gama largă de controale de formular încorporate, puteți adăuga controale personalizate la formular, după cum urmează:

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

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

Există o modalitate de a defini noi metode de formular pentru adăugarea de elemente personalizate (de exemplu, $form->addZip()). Acestea sunt așa-numitele metode de extensie. Dezavantajul este că indicii de cod din editori nu vor funcționa pentru ele.

use Nette\Forms\Container;

// adaugă 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, 'At least 5 numbers', '[0-9]{5}');
});

// utilizare
$form->addZip('zip', 'ZIP code:');

Câmpuri de nivel scăzut

Pentru a adăuga un element la formular, nu trebuie să apelați $form->addXyz(). În schimb, elementele din formular pot fi introduse exclusiv în șabloane. Acest lucru este util dacă, de exemplu, trebuie să generați elemente dinamice:

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

După trimitere, puteți prelua valorile:

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

În primul parametru, specificați tipul de element (DataFile pentru type=file, DataLine pentru intrările cu o singură linie, cum ar fi text, password sau email și DataText pentru restul). Al doilea parametru corespunde atributului HTML name. Dacă trebuie să păstrați cheile, puteți combina primul parametru cu DataKeys. Acest lucru este util pentru select, radioList sau checkboxList.

getHttpData() returnează datele de intrare aseptizate. În acest caz, acesta va fi întotdeauna un array de șiruri UTF-8 valide, indiferent de atacatorul trimis de formular. Este o alternativă la lucrul direct cu $_POST sau $_GET dacă doriți să primiți date sigure.