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.

Utilizați setHtmlType() pentru a schimba caracterul elementului de intrare în search, tel, url, range, date, datetime-local, month, time, week, color. În locul tipurilor number și email, vă recomandăm să utilizați addInteger și addEmail, care oferă 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('level', 'Level:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Level must be between %d and %d.', [0, 100]);

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.

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

Renderizare:

Validare:

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

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

Rețineți că browserul nu trimite deloc câmpurile dezactivate către server, astfel încât nici măcar nu le veți găsi în datele returnate de funcția $form->getValues().

Dacă setați o valoare implicită pentru un câmp, trebuie să faceți acest lucru numai după ce l-ați dezactivat:

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