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