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 spletne strani setHtmlType()
lahko spremenite znak vhodnega elementa v search
,
tel
, url
, range
, month
, week
ali color
. Za druge
tipe, kot so number
, email
, date
, datetime-local
in time
,
obstajajo ločene metode addInteger, addFloat, addEmail, addDate, addTime in addDateTime, ki so opremljene s preverjanjem 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('leto', 'Leto:')
->addRule($form::Range, 'Leto mora biti v razponu od %d do %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', 'Stopnja:')
->setDefaultValue(0)
->addRule($form::Range, 'Raven mora biti v razponu od %d do %d.', [0, 100 |0, 100]);
Nette in Chrome kot decimalno ločilo sprejemata tako vejico kot piko. Da bi tudi Firefox sprejemal vejico, morate ustrezni
jezik nastaviti v atributu HTML lang
, in sicer neposredno temu elementu ali kateremu koli nadrejenemu elementu, na
primer <html lang="cs">
.
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.
addDate(string|int $name, $label=null): DateTimeControl
Doda polje, ki uporabniku omogoča enostaven vnos datuma, sestavljenega iz leta, meseca in dneva (razred DateTimeControl).
Za privzeto vrednost sprejema predmete, ki implementirajo DateTimeInterface
, niz s časom ali število, ki
predstavlja časovni žig UNIX. Enako velja za argumente pravila Min
, Max
ali Range
, ki
določajo najmanjši in največji dovoljeni datum.
$form->addDate('date', 'Date:')
->setDefaultValue(new DateTime)
->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));
Privzeto vrne predmet DateTimeImmutable
. Z metodo setFormat()
lahko določite besedilno obliko ali
časovni žig:
$form->addDate('date', 'Date:')
->setFormat('Y-m-d');
addTime(string|int $name, $label=null, bool $withSeconds = false): DateTimeControl
Doda polje, ki uporabniku omogoča enostaven vnos časa, sestavljenega iz ur, minut in po želji sekund (razred DateTimeControl).
Za privzeto vrednost sprejema predmete, ki implementirajo DateTimeInterface
, niz s časom ali število, ki
predstavlja časovni žig UNIX. Uporabijo se samo podatki o času iz teh vnosov; datum se ne upošteva. Enako velja za argumente
pravil Min
, Max
ali Range
, ki določajo najmanjši in največji dovoljeni čas. Če je
najmanjša nastavljena vrednost višja od največje, se ustvari časovno območje, ki zajema polnoč.
$form->addTime('time', 'Time:', withSeconds: true)
->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);
Privzeto vrne objekt DateTimeImmutable
(z datumom 1. januar, leto 1). Z metodo setFormat()
lahko
določite obliko besedila:
$form->addTime('time', 'Time:')
->setFormat('H:i');
addDateTime(string|int $name, $label=null, bool $withSeconds = false): DateTimeControl
Doda polje, ki uporabniku omogoča enostaven vnos datuma in časa, sestavljenega iz leta, meseca, dneva, ur, minut in po želji sekund (razred DateTimeControl).
Za privzeto vrednost sprejema predmete, ki implementirajo DateTimeInterface
, niz s časom ali število, ki
predstavlja časovni žig UNIX. Enako velja za argumente pravila Min
, Max
ali Range
, ki
določajo najmanjši in največji dovoljeni datum.
$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'));
Privzeto vrne predmet DateTimeImmutable
. Z metodo setFormat()
lahko določite besedilno obliko ali
časovni žig:
$form->addDateTime('datetime')
->setFormat(DateTimeControl::FormatTimestamp);
addColor(string|int $name, $label=null): ColorPicker
Doda polje za izbiro barve (razred ColorPicker). Barva je niz v obliki
#rrggbb
. Če uporabnik ne opravi izbire, je privzeta vrnjena barva črna #000000
.
$form->addColor('color', 'Color:')
->setDefaultValue('#3C8ED7');
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();
Brskalnik onemogočenih polj sploh ne pošlje strežniku, zato jih v podatkih, ki jih vrne funkcija
$form->getValues()
, ne boste našli. Če pa nastavite setOmitted(false)
, bo Nette njihovo vrednost
vključil v te podatke.
Ko pokličete setDisabled()
, se vrednost polja izbriše. Če nastavljate privzeto vrednost, morate to storiti po
tem, ko ste jo deaktivirali:
$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.