Elementi obrazca

Pregled standardnih elementov obrazca.

addText (string|int $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput

Doda enovrstično besedilno polje (razred TextInput). Če uporabnik polja ne izpolni, vrne prazen niz '', ali pa s pomočjo setNullable() lahko določite, da vrne null.

$form->addText('name', 'Ime:')
	->setRequired()
	->setNullable();

Samodejno validira UTF-8, obreže leve in desne presledke ter odstrani prelome vrstic, ki bi jih lahko poslal napadalec.

Maksimalno dolžino lahko omejite s pomočjo setMaxLength(). Spreminjanje vrednosti, ki jo vnese uporabnik, omogoča addFilter().

S pomočjo setHtmlType() lahko spremenite vizualni značaj besedilnega polja na tipe, kot so search, tel ali url, glej specifikacijo. Ne pozabite, da je sprememba tipa le vizualna in ne nadomešča funkcije validacije. Za tip url je priporočljivo dodati specifično validacijsko pravilo URL.

Za druge tipe vnosov, kot so number, range, email, date, datetime-local, time in color, uporabite specializirane metode, kot so addInteger, addFloat, addEmail addDate, addTime, addDateTime in addColor, ki zagotavljajo strežniško validacijo. Tipi month in week še niso popolnoma podprti v vseh brskalnikih.

Elementu lahko nastavite t.i. empty-value, kar je nekaj podobnega privzeti vrednosti, a če je uporabnik ne spremeni, element vrne prazen niz ali null.

$form->addText('phone', 'Telefon:')
	->setHtmlType('tel')
	->setEmptyValue('+386');

addTextArea (string|int $name, $label=null): TextArea

Doda polje za vnos večvrstičnega besedila (razred TextArea). Če uporabnik polja ne izpolni, vrne prazen niz '', ali pa s pomočjo setNullable() lahko določite, da vrne null.

$form->addTextArea('note', 'Opomba:')
	->addRule($form::MaxLength, 'Opomba je predolga', 10000);

Samodejno validira UTF-8 in normalizira ločila vrstic na \n. V nasprotju z enovrstičnim vnosnim poljem ne pride do obrezovanja presledkov.

Maksimalno dolžino lahko omejite s pomočjo setMaxLength(). Spreminjanje vrednosti, ki jo vnese uporabnik, omogoča addFilter(). Lahko nastavite t.i. empty-value s pomočjo setEmptyValue().

addInteger (string|int $name, $label=null): TextInput

Doda polje za vnos celega števila (razred TextInput). Vrne bodisi integer ali null, če uporabnik ničesar ne vnese.

$form->addInteger('year', 'Leto:')
	->addRule($form::Range, 'Leto mora biti v obsegu od %d do %d.', [1900, 2023]);

Element se izriše kot <input type="number">. Z uporabo metode setHtmlType() lahko spremenite tip na range za prikaz v obliki drsnika ali na text, če preferirate standardno besedilno polje brez posebnega obnašanja tipa number.

addFloat (string|int $name, $label=null): TextInput

Doda polje za vnos decimalnega števila (razred TextInput). Vrne bodisi float ali null, če uporabnik ničesar ne vnese.

$form->addFloat('level', 'Raven:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Raven mora biti v obsegu od %d do %d.', [0, 100]);

Nette in brskalnik Chrome sprejemata kot ločilo decimalnih mest tako vejico kot piko. Da bi bila ta funkcionalnost na voljo tudi v Firefoxu, je priporočljivo nastaviti atribut lang bodisi za dani element ali za celotno stran, na primer <html lang="sl">.

addEmail (string|int $name, $label=null, int $maxLength=255): TextInput

Doda polje za vnos e-poštnega naslova (razred TextInput). Če uporabnik polja ne izpolni, vrne prazen niz '', ali pa s pomočjo setNullable() lahko določite, da vrne null.

$form->addEmail('email', 'E-pošta:');

Preveri, ali je vrednost veljaven e-poštni naslov. Ne preverja se, ali domena dejansko obstaja, preverja se le sintaksa. Samodejno validira UTF-8, obreže leve in desne presledke.

Maksimalno dolžino lahko omejite s pomočjo setMaxLength(). Spreminjanje vrednosti, ki jo vnese uporabnik, omogoča addFilter(). Lahko nastavite t.i. empty-value s pomočjo setEmptyValue().

addPassword (string|int $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput

Doda polje za vnos gesla (razred TextInput).

$form->addPassword('password', 'Geslo:')
	->setRequired()
	->addRule($form::MinLength, 'Geslo mora imeti vsaj %d znakov', 8)
	->addRule($form::Pattern, 'Mora vsebovati števko', '.*[0-9].*');

Pri ponovnem prikazu obrazca bo polje prazno. Samodejno validira UTF-8, obreže leve in desne presledke ter odstrani prelome vrstic, ki bi jih lahko poslal napadalec.

addCheckbox (string|int $name, $caption=null): Checkbox

Doda potrditveno polje (razred Checkbox). Vrne vrednost bodisi true ali false, glede na to, ali je označeno.

$form->addCheckbox('agree', 'Strinjam se s pogoji')
	->setRequired('Potrebno je strinjanje s pogoji');

addCheckboxList (string|int $name, $label=null, ?array $items=null): CheckboxList

Doda potrditvena polja za izbiro več postavk (razred CheckboxList). Vrne polje ključev izbranih postavk. Metoda getSelectedItems() vrne vrednosti namesto ključev.

$form->addCheckboxList('colors', 'Barve:', [
	'r' => 'rdeča',
	'g' => 'zelena',
	'b' => 'modra',
]);

Polje ponujenih postavk predamo kot tretji parameter ali z metodo setItems().

S pomočjo setDisabled(['r', 'g']) lahko deaktivirate posamezne postavke.

Element samodejno preverja, da ni prišlo do ponarejanja in da so izbrane postavke dejansko ene izmed ponujenih in niso bile deaktivirane. Z metodo getRawValue() lahko pridobite poslane postavke brez tega pomembnega preverjanja.

Pri nastavitvi privzetih izbranih postavk tudi preverja, da gre za ene izmed ponujenih, sicer vrže izjemo. To preverjanje lahko izklopite s pomočjo checkDefaultValue(false).

Če pošiljate obrazec z metodo GET, lahko izberete kompaktnejši način prenosa podatkov, ki prihrani velikost poizvedbenega niza (query string). Aktivira se z nastavitvijo HTML atributa obrazca:

$form->setHtmlAttribute('data-nette-compact');

addRadioList (string|int $name, $label=null, ?array $items=null): RadioList

Doda izbirne gumbe (radio buttons) (razred RadioList). Vrne ključ izbrane postavke ali null, če uporabnik ničesar ni izbral. Metoda getSelectedItem() vrne vrednost namesto ključa.

$sex = [
	'm' => 'moški',
	'f' => 'ženska',
];
$form->addRadioList('gender', 'Spol:', $sex);

Polje ponujenih postavk predamo kot tretji parameter ali z metodo setItems().

S pomočjo setDisabled(['m', 'f']) lahko deaktivirate posamezne postavke.

Element samodejno preverja, da ni prišlo do ponarejanja in da je izbrana postavka dejansko ena izmed ponujenih in ni bila deaktivirana. Z metodo getRawValue() lahko pridobite poslano postavko brez tega pomembnega preverjanja.

Pri nastavitvi privzete izbrane postavke tudi preverja, da gre za eno izmed ponujenih, sicer vrže izjemo. To preverjanje lahko izklopite s pomočjo checkDefaultValue(false).

addSelect (string|int $name, $label=null, ?array $items=null, ?int $size=null): SelectBox

Doda izbirno polje (select box) (razred SelectBox). Vrne ključ izbrane postavke ali null, če uporabnik ničesar ni izbral. Metoda getSelectedItem() vrne vrednost namesto ključa.

$countries = [
	'CZ' => 'Češka Republika',
	'SK' => 'Slovaška',
	'GB' => 'Velika Britanija',
];

$form->addSelect('country', 'Država:', $countries)
	->setDefaultValue('SK');

Polje ponujenih postavk predamo kot tretji parameter ali z metodo setItems(). Postavke so lahko tudi dvodimenzionalno polje:

$countries = [
	'Europe' => [
		'CZ' => 'Češka Republika',
		'SK' => 'Slovaška',
		'GB' => 'Velika Britanija',
	],
	'CA' => 'Kanada',
	'US' => 'ZDA',
	'?'  => 'druga',
];

Pri izbirnih poljih ima pogosto prva postavka poseben pomen, služi kot poziv k akciji. Za dodajanje takšne postavke služi metoda setPrompt().

$form->addSelect('country', 'Država:', $countries)
	->setPrompt('Izberite državo');

S pomočjo setDisabled(['CZ', 'SK']) lahko deaktivirate posamezne postavke.

Pri nastavitvi privzete izbrane postavke tudi preverja, da gre za eno izmed ponujenih, sicer vrže izjemo. To preverjanje lahko izklopite s pomočjo checkDefaultValue(false).

addMultiSelect (string|int $name, $label=null, ?array $items=null, ?int $size=null): MultiSelectBox

Doda izbirno polje za izbiro več postavk (razred MultiSelectBox). Vrne polje ključev izbranih postavk. Metoda getSelectedItems() vrne vrednosti namesto ključev.

$form->addMultiSelect('countries', 'Države:', $countries);

Polje ponujenih postavk predamo kot tretji parameter ali z metodo setItems(). Postavke so lahko tudi dvodimenzionalno polje.

S pomočjo setDisabled(['CZ', 'SK']) lahko deaktivirate posamezne postavke.

Pri nastavitvi privzetih izbranih postavk tudi preverja, da gre za ene izmed ponujenih, sicer vrže izjemo. To preverjanje lahko izklopite s pomočjo checkDefaultValue(false).

addUpload (string|int $name, $label=null): UploadControl

Doda polje za nalaganje datoteke (razred UploadControl). Vrne objekt FileUpload, in to tudi v primeru, da uporabnik nobene datoteke ni poslal, kar lahko ugotovite z metodo FileUpload::hasFile().

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatar mora biti JPEG, PNG, GIF, WebP ali AVIF.')
	->addRule($form::MaxFileSize, 'Maksimalna velikost je 1 MB.', 1024 * 1024);

Če se datoteka ne uspe pravilno naložiti, obrazec ni uspešno poslan in prikaže se napaka. Tj. pri uspešni oddaji ni treba preverjati metode FileUpload::isOk().

Nikoli ne zaupajte originalnemu imenu datoteke, vrnjenemu z metodo FileUpload::getName(), klient bi lahko poslal škodljivo ime datoteke z namenom poškodovati ali vdreti v vašo aplikacijo.

Pravili MimeType in Image zaznata zahtevani tip na podlagi signature datoteke in ne preverjata njene integritete. Ali slika ni poškodovana, lahko ugotovite na primer s poskusom njenega nalaganja.

addMultiUpload (string|int $name, $label=null): UploadControl

Doda polje za nalaganje več datotek hkrati (razred UploadControl). Vrne polje objektov FileUpload. Metoda FileUpload::hasFile() pri vsakem od njih bo vračala true.

$form->addMultiUpload('files', 'Datoteke:')
	->addRule($form::MaxLength, 'Maksimalno lahko naložite %d datotek', 10);

Če se katera koli datoteka ne uspe pravilno naložiti, obrazec ni uspešno poslan in prikaže se napaka. Tj. pri uspešni oddaji ni treba preverjati metode FileUpload::isOk().

Nikoli ne zaupajte originalnim imenom datotek, vrnjenim z metodo FileUpload::getName(), klient bi lahko poslal škodljivo ime datoteke z namenom poškodovati ali vdreti v vašo aplikacijo.

addDate (string|int $name, $label=null): DateTimeControl

Doda polje, ki uporabniku omogoča enostaven vnos datuma, sestavljenega iz leta, meseca in dneva (razred DateTimeControl).

Kot privzeto vrednost sprejema bodisi objekte, ki implementirajo vmesnik DateTimeInterface, niz s časom ali število, ki predstavlja UNIX časovni žig. Enako velja za argumente pravil Min, Max ali Range, ki definirajo minimalni in maksimalni dovoljeni datum.

$form->addDate('date', 'Datum:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'Datum mora biti vsaj en mesec star.', new DateTime('-1 month'));

Standardno vrne objekt DateTimeImmutable, z metodo setFormat() lahko specificirate besedilni format ali časovni žig:

$form->addDate('date', 'Datum:')
	->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 opcijsko tudi sekund (razred DateTimeControl).

Kot privzeto vrednost sprejema bodisi objekte, ki implementirajo vmesnik DateTimeInterface, niz s časom ali število, ki predstavlja UNIX časovni žig. Iz teh vnosov je uporabljena le časovna informacija, datum je ignoriran. Enako velja za argumente pravil Min, Max ali Range, ki definirajo minimalni in maksimalni dovoljeni čas. Če je nastavljena minimalna vrednost višja od maksimalne, se ustvari časovni obseg, ki presega polnoč.

$form->addTime('time', 'Čas:', withSeconds: true)
	->addRule($form::Range, 'Čas mora biti v obsegu od %d do %d.', ['12:30', '13:30']);

Standardno vrne objekt DateTimeImmutable (z datumom 1. januarja leta 1), z metodo setFormat() lahko specificirate besedilni format:

$form->addTime('time', 'Čas:')
	->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 opcijsko tudi sekund (razred DateTimeControl).

$form->addDateTime('datetime', 'Datum in čas:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'Datum mora biti vsaj en mesec star.', new DateTime('-1 month'));

Standardno vrne objekt DateTimeImmutable, z metodo setFormat() lahko specificirate besedilni format 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 izbire ne opravi, se vrne črna barva #000000.

$form->addColor('color', 'Barva:')
	->setDefaultValue('#3C8ED7');

addHidden (string|int $name, ?string $default=null): HiddenField

Doda skrito polje (razred HiddenField).

$form->addHidden('userid');

S pomočjo setNullable() lahko nastavite, da vrne null namesto praznega niza. Spreminjanje poslane vrednosti omogoča addFilter().

Čeprav je element skrit, je pomembno se zavedati, da lahko vrednost še vedno spremeni ali ponaredi napadalec. Vedno temeljito preverjajte in validirajte vse prejete vrednosti na strežniški strani, da preprečite varnostna tveganja, povezana z manipulacijo podatkov.

addSubmit (string|int $name, $caption=null): SubmitButton

Doda gumb za oddajo (razred SubmitButton).

$form->addSubmit('submit', 'Pošlji');

V obrazcu je mogoče imeti tudi več gumbov za oddajo:

$form->addSubmit('register', 'Registriraj');
$form->addSubmit('cancel', 'Prekliči');

Za ugotovitev, na katerega od njih je bilo kliknjeno, uporabite:

if ($form['register']->isSubmittedBy()) {
  // ...
}

Če ne želite validirati celotnega obrazca ob pritisku na gumb (na primer pri gumbih Prekliči ali Predogled), uporabite setValidationScope().

addButton (string|int $name, $caption): Button

Doda gumb (razred Button), ki nima funkcije oddaje. Lahko ga torej uporabite za kakšno drugo funkcijo, npr. klic JavaScript funkcije ob kliku.

$form->addButton('raise', 'Zvišaj plačo')
	->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', '/pot/do/slike');

Pri uporabi več gumbov za oddajo lahko ugotovite, na katerega je bilo kliknjeno, s pomočjo $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Doda podobrazec (razred Container), ali vsebnik, v katerega lahko dodajate druge elemente na enak način, kot jih dodajamo v obrazec. Delujejo tudi metode setDefaults() ali getValues().

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Vaše ime:');
$sub1->addEmail('email', 'E-pošta:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Vaše ime:');
$sub2->addEmail('email', 'E-pošta:');

Poslani podatki se nato vrnejo kot večdimenzionalna struktura:

[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]

Pregled nastavitev

Pri vseh elementih lahko kličemo naslednje metode (popoln pregled v API dokumentaciji):

`setDefaultValue($value)`	nastavi privzeto vrednost
`getValue()`	pridobi trenutno vrednost
`setOmitted()`	Izpustitev vrednosti
`setDisabled()`	Deaktivacija elementov

Izrisovanje:

`setCaption($caption)`	spremeni oznako elementa
`setTranslator($translator)`	nastavi prevajalnik
`setHtmlAttribute($name, $value)`	nastavi HTML atribut elementa
`setHtmlId($id)`	nastavi HTML atribut `id`
`setHtmlType($type)`	nastavi HTML atribut `type`
`setHtmlName($name)`	nastavi HTML atribut `name`
`setOption($key, $value)`	nastavitve za izrisovanje

Validacija:

`setRequired()`	obvezni element
`addRule()`	nastavitev validacijsko pravilo
`addCondition()`, `addConditionOn()`	nastavi validacijski pogoj
`addError($message)`	predaja sporočila o napaki

Pri elementih addText(), addPassword(), addTextArea(), addEmail(), addInteger() lahko kličemo naslednje metode:

`setNullable()`	nastavi, ali getValue() vrne `null` namesto praznega niza
`setEmptyValue($value)`	nastavi posebno vrednost, ki se šteje za prazen niz
`setMaxLength($length)`	nastavi maksimalno število dovoljenih znakov
`addFilter($filter)`	prilagoditev vnosa

Izpustitev vrednosti

Če nas vrednost, ki jo je vnesel uporabnik, ne zanima, jo lahko s pomočjo setOmitted() izpustimo iz rezultata metode $form->getValues() ali iz podatkov, predanih handlerjem. To je koristno za različna gesla za preverjanje, antispam elemente itd.

$form->addPassword('passwordVerify', 'Geslo za preverjanje:')
	->setRequired('Prosimo, vnesite geslo še enkrat za preverjanje')
	->addRule($form::Equal, 'Gesli se ne ujemata', $form['password'])
	->setOmitted();

Deaktivacija elementov

Elemente lahko deaktivirate s pomočjo setDisabled(). Takšnega elementa uporabnik ne more urejati.

$form->addText('username', 'Uporabniško ime:')
	->setDisabled();

Onemogočeni elementi brskalnik sploh ne pošilja na strežnik, torej jih niti ne najdete v podatkih, vrnjenih s funkcijo $form->getValues(). Če pa nastavite setOmitted(false), Nette v te podatke vključi njihovo privzeto vrednost.

Pri klicu setDisabled() se iz varnostnih razlogov izbriše vrednost elementa. Če nastavljate privzeto vrednost, je to treba storiti šele po njegovi deaktivaciji:

$form->addText('username', 'Uporabniško ime:')
	->setDisabled()
	->setDefaultValue($userName);

Alternativa onemogočenim elementom so elementi s HTML atributom readonly, ki jih brskalnik pošilja na strežnik. Čeprav je element samo za branje, je pomembno se zavedati, da lahko njegovo vrednost še vedno spremeni ali ponaredi napadalec.

Lastni elementi

Poleg široke palete vgrajenih elementov obrazca lahko v obrazec dodajate lastne elemente na ta način:

$form->addComponent(new DateInput('Datum:'), 'date');
// alternativna sintaksa: $form['date'] = new DateInput('Datum:');

Obrazec je potomec razreda Container in posamezni elementi so potomci Component.

Obstaja način, kako definirati nove metode obrazca, ki služijo za dodajanje lastnih elementov (npr. $form->addZip()). Gre za t.i. extension methods. Slabost je, da zanje ne bo delovalo predlaganje v urejevalnikih.

use Nette\Forms\Container;

// dodamo 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, 'Vsaj 5 številk', '[0-9]{5}');
});

// uporaba
$form->addZip('zip', 'Poštna številka:');

Nizkonivojski elementi

Lahko uporabljamo tudi elemente, ki jih zapišemo samo v predlogi in jih ne dodamo v obrazec z nobeno od metod $form->addXyz(). Ko na primer izpisujemo zapise iz podatkovne baze in vnaprej ne vemo, koliko jih bo in kakšne ID-je bodo imeli, in želimo pri vsaki vrstici prikazati potrditveno polje ali izbirni gumb, ga zadostuje kodirati v predlogi:

{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}

In po oddaji vrednost ugotovimo:

$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');

kjer prvi parameter je tip elementa (DataFile za type=file, DataLine za enovrstične vnose kot text, password, email ipd. in DataText za vse ostale) in drugi parameter sel[] ustreza HTML atributu name. Tip elementa lahko kombiniramo z vrednostjo DataKeys, ki ohrani ključe elementov. To je koristno zlasti za select, radioList in checkboxList.

Bistveno je, da getHttpData() vrne sanirano vrednost, v tem primeru bo to vedno polje veljavnih UTF-8 nizov, ne glede na to, kaj bi poskušal napadalec podtakniti strežniku. Gre za analogijo neposrednega dela z $_POST ali $_GET, vendar s to bistveno razliko, da vedno vrne čiste podatke, tako kot ste navajeni pri standardnih elementih Nette obrazcev.