Controale de formular

Prezentare generală a controalelor de formular încorporate.

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

Folosind setHtmlType(), puteți schimba caracterul elementului de intrare în search, tel, url, range, month, week, sau color. Pentru alte tipuri precum number, email, , date, datetime-local și time, există metode separate addInteger, addFloat, addEmail, addDate, addTime și addDateTime, care sunt însoțite de validare pe server.

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

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

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 Chrome acceptă atât virgula, cât și punctul ca separator zecimal. Pentru ca Firefox să accepte și virgula, trebuie să setați limba corespunzătoare în atributul HTML lang, fie direct la acest element, fie la orice element părinte, de exemplu <html lang="cs">.

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

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

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

addMultiSelect(string|int $name, $label=null, array $items=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.

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

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.

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.

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

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

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

Pentru a dezactiva o intrare, puteți apela setDisabled(). Un astfel de câmp nu poate fi editat de către utilizator.

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

Câmpurile dezactivate nu sunt trimise de către browser către server, 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 în aceste date.

Atunci când apelați setDisabled(), valoarea câmpului este ștearsă. Dacă setați o valoare implicită, trebuie să faceți acest lucru după dezactivarea acesteia:

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

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.

versiune: 4.0