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.

različica: 4.0