Krmilniki obrazca
Pregled vgrajenih kontrolnih elementov obrazca.
addText(string|int $name, $label=null): TextInput
Doda enovrstično besedilno polje (razred TextInput). Če uporabnik ne izpolni polja, vrne
prazen niz ''
, ali pa ga z uporabo setNullable()
spremeni tako, da vrne null
.
$form->addText('name', 'Name:')
->setRequired()
->setNullable();
Samodejno potrdi UTF-8, obreže leve in desne bele prostore ter odstrani prelome vrstic, ki bi jih lahko poslal napadalec.
Največjo dolžino lahko omejite z uporabo setMaxLength()
. S funkcijo addFilter() lahko spremenite uporabniško vneseno
vrednost.
Z uporabo setHtmlType()
spremenite znak vhodnega elementa v search
,
tel
, url
, range
, date
, datetime-local
, month
,
time
, week
, color
. Namesto tipov number
in email
priporočamo
uporabo tipov addInteger in addEmail, ki zagotavljata preverjanje na
strani strežnika.
$form->addText('color', 'Choose color:')
->setHtmlType('color')
->addRule($form::Pattern, 'invalid value', '[0-9a-f]{6}');
Za element lahko nastavite tako imenovano prazno vrednost, ki je nekaj podobnega kot privzeta vrednost, vendar če je uporabnik
ne prepiše, vrne prazen niz ali null
.
$form->addText('phone', 'Phone:')
->setHtmlType('tel')
->setEmptyValue('+420');
addTextArea(string|int $name, $label=null): TextArea
Doda večvrstično besedilno polje (razred TextArea). Če uporabnik ne izpolni polja, vrne
prazen niz ''
, ali pa ga z uporabo setNullable()
spremeni tako, da vrne null
.
$form->addTextArea('note', 'Note:')
->addRule($form::MaxLength, 'Your note is way too long', 10000);
Samodejno preveri UTF-8 in normalizira prelome vrstic na \n
. Za razliko od enovrstičnega vnosnega polja ne
obrezuje belih pik.
Največjo dolžino lahko omejite z uporabo setMaxLength()
. Funkcija addFilter() omogoča spreminjanje uporabniško
vnesene vrednosti. Tako imenovano prazno vrednost lahko nastavite z uporabo setEmptyValue()
.
addInteger(string|int $name, $label=null): TextInput
Doda vnosno polje za celo število (razred TextInput). Vrne celo število ali
null
, če uporabnik ne vnese ničesar.
$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
Doda polje e-poštnega naslova s preverjanjem veljavnosti (razred TextInput). Če uporabnik ne izpolni polja, vrne
prazen niz ''
, ali pa ga z uporabo setNullable()
spremeni tako, da vrne null
.
$form->addEmail('email', 'Email:');
Preveri, ali je vrednost veljavni e-poštni naslov. Ne preveri, ali domena dejansko obstaja, preveri se le sintaksa. Samodejno preveri UTF-8, obreže leve in desne bele prostore.
Največjo dolžino lahko omejite z uporabo setMaxLength()
. S funkcijo addFilter() lahko spremenite uporabniško vneseno
vrednost. Tako imenovano prazno vrednost lahko nastavite z uporabo setEmptyValue()
.
addPassword(string|int $name, $label=null): TextInput
Doda polje za geslo (razred 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].*');
Ob ponovnem pošiljanju obrazca bo vnos prazno polje. Samodejno potrdi UTF-8, obreže leve in desne bele prostore ter odstrani prelome vrstic, ki bi jih lahko poslal napadalec.
addCheckbox(string|int $name, $caption=null): Checkbox
Doda potrditveno polje (razred Checkbox).
Polje vrne true
ali false
, odvisno od tega, ali je označeno.
$form->addCheckbox('agree', 'I agree with terms')
->setRequired('You must agree with our terms');
addCheckboxList(string|int $name, $label=null, array $items=null): CheckboxList
Doda seznam potrditvenih polj za izbiro več elementov (razred CheckboxList). Vrne polje ključev izbranih
elementov. Metoda getSelectedItems()
namesto ključev vrne vrednosti.
$form->addCheckboxList('colors', 'Colors:', [
'r' => 'red',
'g' => 'green',
'b' => 'blue',
]);
Polje elementov posredujemo kot tretji parameter ali z metodo setItems()
.
Uporabite lahko setDisabled(['r', 'g'])
za onemogočanje posameznih elementov.
Element samodejno preveri, da ni prišlo do ponarejanja in da so izbrani elementi dejansko eni od ponujenih ter da niso bili
onemogočeni. Z metodo getRawValue()
lahko pridobite predložene elemente brez tega pomembnega preverjanja.
Če so nastavljene privzete vrednosti, se prav tako preveri, ali gre za enega od ponujenih elementov, sicer se vrže izjema. To
preverjanje je mogoče izklopiti z metodo checkDefaultValue(false)
.
addRadioList(string|int $name, $label=null, array $items=null): RadioList
Doda radijske gumbe (razred RadioList).
Vrne ključ izbranega elementa ali null
, če uporabnik ni izbral ničesar. Metoda getSelectedItem()
namesto ključa vrne vrednost.
$sex = [
'm' => 'male',
'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);
Polje elementov posredujemo kot tretji parameter ali z metodo setItems()
.
Uporabite lahko setDisabled(['m'])
za onemogočanje posameznih elementov.
Element samodejno preveri, ali ni prišlo do ponarejanja in ali je izbrani element dejansko eden od ponujenih ter ni bil
onemogočen. Z metodo getRawValue()
lahko pridobite ponujeni element brez tega pomembnega preverjanja.
Če je nastavljena privzeta vrednost, preveri tudi, ali gre za enega od ponujenih elementov, sicer vrže izjemo. To preverjanje
je mogoče izklopiti z metodo checkDefaultValue(false)
.
addSelect(string|int $name, $label=null, array $items=null): SelectBox
Doda izbirno polje (razred SelectBox).
Vrne ključ izbranega elementa ali null
, če uporabnik ni izbral ničesar. Metoda getSelectedItem()
namesto ključa vrne vrednost.
$countries = [
'CZ' => 'Czech republic',
'SK' => 'Slovakia',
'GB' => 'United Kingdom',
];
$form->addSelect('country', 'Country:', $countries)
->setDefaultValue('SK');
Polje elementov posredujemo kot tretji parameter ali z metodo setItems()
. Polje elementov je lahko tudi
dvodimenzionalno:
$countries = [
'Europe' => [
'CZ' => 'Czech republic',
'SK' => 'Slovakia',
'GB' => 'United Kingdom',
],
'CA' => 'Canada',
'US' => 'USA',
'?' => 'other',
];
Pri izbirnih poljih ima prvi element pogosto poseben pomen, saj služi kot poziv k dejanju. Za dodajanje takega elementa
uporabite metodo setPrompt()
.
$form->addSelect('country', 'Country:', $countries)
->setPrompt('Pick a country');
Uporabite lahko setDisabled(['CZ', 'SK'])
za onemogočanje posameznih elementov.
Element samodejno preveri, ali ni prišlo do ponarejanja in ali je izbrani element dejansko eden od ponujenih ter ni bil
onemogočen. Z metodo getRawValue()
lahko pridobite ponujeni element brez tega pomembnega preverjanja.
Če je nastavljena privzeta vrednost, preveri tudi, ali gre za enega od ponujenih elementov, sicer vrže izjemo. To preverjanje
je mogoče izklopiti z metodo checkDefaultValue(false)
.
addMultiSelect(string|int $name, $label=null, array $items=null): MultiSelectBox
Doda izbirno polje za več možnosti (razred MultiSelectBox). Vrne polje ključev
izbranih elementov. Metoda getSelectedItems()
namesto ključev vrne vrednosti.
$form->addMultiSelect('countries', 'Countries:', $countries);
Polje elementov posredujemo kot tretji parameter ali z metodo setItems()
. Polje elementov je lahko tudi
dvodimenzionalno.
Uporabite lahko setDisabled(['CZ', 'SK'])
za onemogočanje posameznih elementov.
Element samodejno preveri, da ni prišlo do ponarejanja in da so izbrani elementi dejansko eni od ponujenih ter da niso bili
onemogočeni. Z metodo getRawValue()
lahko pridobite predložene elemente brez tega pomembnega preverjanja.
Če so nastavljene privzete vrednosti, se prav tako preveri, ali gre za enega od ponujenih elementov, sicer se vrže izjema. To
preverjanje je mogoče izklopiti z metodo checkDefaultValue(false)
.
addUpload(string|int $name, $label=null): UploadControl
Doda polje za nalaganje datotek (razred UploadControl). Vrne objekt FileUpload, tudi če uporabnik ni naložil datoteke, kar je
mogoče ugotoviti z metodo 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);
Če datoteka ni bila pravilno naložena, obrazec ni bil uspešno poslan in se prikaže napaka. To pomeni, da metode
FileUpload::isOk()
ni treba preverjati.
Ne zaupajte izvirnemu imenu datoteke, ki ga vrne metoda FileUpload::getName()
, odjemalec lahko pošlje zlonamerno
ime datoteke z namenom poškodovanja ali vdora v vašo aplikacijo.
Pravili MimeType
in Image
zahtevano vrsto datoteke ali slike odkrijeta na podlagi njenega podpisa.
Celovitost celotne datoteke se ne preverja. Ali slika ni poškodovana, lahko ugotovite na primer tako, da jo poskusite naložiti.
addMultiUpload(string|int $name, $label=null): UploadControl
Doda polje za nalaganje več datotek (razred UploadControl). Vrne polje predmetov FileUpload. Metoda FileUpload::hasFile()
bo vrnila
true
za vsakega od njih.
$form->addMultiUpload('files', 'Files:')
->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);
Če se ena od datotek ne naloži pravilno, obrazec ni bil uspešno poslan in se prikaže napaka. To pomeni, da metode
FileUpload::isOk()
ni treba preverjati.
Ne zaupajte izvirnim imenom datotek, ki jih vrne metoda FileUpload::getName()
, odjemalec lahko pošlje zlonamerno
ime datoteke z namenom poškodovanja ali vdora v vašo aplikacijo.
Pravili MimeType
in Image
zahtevano vrsto datoteke ali slike odkrijeta na podlagi njenega podpisa.
Celovitost celotne datoteke se ne preverja. Ali slika ni poškodovana, lahko ugotovite na primer tako, da jo poskusite naložiti.
addHidden(string|int $name, string $default=null): HiddenField
Doda skrito polje (razred HiddenField).
$form->addHidden('userid');
Uporabite setNullable()
, da ga spremenite tako, da vrne null
namesto praznega niza. S funkcijo addFilter() lahko spremenite oddano vrednost.
addSubmit(string|int $name, $caption=null): SubmitButton
Doda gumb za oddajo (razred SubmitButton).
$form->addSubmit('submit', 'Register');
V obrazcu je mogoče imeti več kot en gumb za oddajo:
$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');
Če želite ugotoviti, kateri od njih je bil kliknjen, uporabite:
if ($form['register']->isSubmittedBy()) {
// ...
}
Če ne želite preveriti obrazca, ko je pritisnjen gumb za oddajo (kot sta gumba Preklic ali Predogled), lahko to izklopite s funkcijo setValidationScope().
addButton(string|int $name, $caption): Button
Doda gumb (razred Button) brez funkcije submit. Uporaben je za vezavo drugih funkcij na id, na primer akcije JavaScript.
$form->addButton('raise', 'Raise salary')
->setHtmlAttribute('onclick', 'raiseSalary()');
addImageButton(string|int $name, string $src=null, string $alt=null): ImageButton
Doda gumb za oddajo v obliki slike (razred ImageButton).
$form->addImageButton('submit', '/path/to/image');
Če uporabljate več gumbov za oddajo, lahko ugotovite, kateri od njih je bil kliknjen z
$form['submit']->isSubmittedBy()
.
addContainer(string|int $name): Container
Doda podobrazec (razred Container) ali vsebnik, ki
ga je mogoče obravnavati enako kot obrazec. To pomeni, da lahko uporabite metode, kot sta setDefaults()
ali
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:');
Poslani podatki se nato vrnejo kot večdimenzionalna struktura:
[
'first' => [
'name' => /* ... */,
'email' => /* ... */,
],
'second' => [
'name' => /* ... */,
'email' => /* ... */,
],
]
Pregled nastavitev
Za vse elemente lahko pokličemo naslednje metode (za popoln pregled glejte dokumentacijo API ):
setDefaultValue($value) |
nastavi privzeto vrednost |
getValue() |
pridobitev trenutne vrednosti |
setOmitted() |
izpuščene vrednosti |
setDisabled() |
onemogočanje vnosov |
Izrisovanje:
setCaption($caption) |
sprememba napisa elementa |
setTranslator($translator) |
nastavi prevajalnik |
setHtmlAttribute($name, $value) |
nastavi atribut HTML elementa |
setHtmlId($id) |
nastavi atribut HTML id |
setHtmlType($type) |
nastavi atribut HTML type |
setHtmlName($name) |
nastavi atribut HTML name |
setOption($key, $value) |
nastavi podatke za upodabljanje |
Potrjevanje:
setRequired() |
obvezno polje |
addRule() |
določitev pravila potrjevanja |
addCondition() , addConditionOn() |
nastavitev pogoja potrjevanja |
addError($message) |
posredovanje sporočila o napaki |
Za elemente addText()
, addPassword()
, addTextArea()
, addEmail()
,
addInteger()
se lahko kličejo naslednje metode:
setNullable() |
določa, ali funkcija getValue() vrne null namesto praznega niza |
setEmptyValue($value) |
določa posebno vrednost, ki se obravnava kot prazen niz |
setMaxLength($length) |
določa največje dovoljeno število znakov |
addFilter($filter) |
spreminjanje vhodnih vrednosti |
Izpuščene vrednosti
Če vas vrednost, ki jo je vnesel uporabnik, ne zanima, jo lahko z uporabo setOmitted()
izpustimo iz rezultata,
ki ga zagotovi metoda $form->getValues()
ali posreduje obdelovalcem. To je primerno za različna gesla za
preverjanje, antispam polja itd.
$form->addPassword('passwordVerify', 'Password again:')
->setRequired('Fill your password again to check for typo')
->addRule($form::Equal, 'Password mismatch', $form['password'])
->setOmitted();
Onemogočanje vnosov
Če želite onemogočiti vhod, lahko pokličete setDisabled()
. Takšnega polja uporabnik ne more urejati.
$form->addText('username', 'User name:')
->setDisabled();
Upoštevajte, da brskalnik onemogočenih polj sploh ne pošlje strežniku, zato jih ne boste našli niti v podatkih, ki jih
vrne funkcija $form->getValues()
.
Če polju določate privzeto vrednost, morate to storiti šele potem, ko ste ga onemogočili:
$form->addText('username', 'User name:')
->setDisabled()
->setDefaultValue($userName);
Prilagojeni gumbi
Poleg širokega nabora vgrajenih kontrolnikov obrazca lahko v obrazec dodate kontrolnike po meri, kot sledi:
$form->addComponent(new DateInput('Date:'), 'date');
// alternativna sintaksa: Datum:");
Obrazec je potomec razreda Container, elementi pa so potomci razreda Component.
Za dodajanje elementov po meri (npr. $form->addZip()
) lahko določite nove metode obrazca. To so tako imenovane
razširitvene metode. Slaba stran je, da namigi za kodo v urejevalnikih zanje ne bodo delovali.
use Nette\Forms\Container;
// doda metodo 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}');
});
// uporaba
$form->addZip('zip', 'ZIP code:');
Polja nizke ravni
Če želite v obrazec dodati element, vam ni treba klicati $form->addXyz()
. Namesto tega lahko elemente
obrazca uvedete izključno v predlogah. To je koristno, če morate na primer ustvariti dinamične elemente:
{foreach $items as $item}
<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}
Po oddaji lahko pridobite vrednosti:
$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');
V prvem parametru določite vrsto elementa (DataFile
za type=file
, DataLine
za
enovrstične vnose, kot so text
, password
ali email
in DataText
za ostale).
Drugi parameter ustreza atributu HTML name
. Če morate ohraniti ključe, lahko prvi parameter kombinirate s
DataKeys
. To je uporabno za select
, radioList
ali checkboxList
.
Parameter getHttpData()
vrne prečiščene vhodne podatke. V tem primeru bo to vedno polje veljavnih nizov UTF-8,
ne glede na to, kaj je napadalec poslal z obrazcem. To je alternativa neposrednemu delu s $_POST
ali
$_GET
, če želite prejeti varne podatke.