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

Izrisovanje:

Potrjevanje:

Za elemente addText(), addPassword(), addTextArea(), addEmail(), addInteger() se lahko kličejo naslednje metode:

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.