Krmilniki obrazca

Pregled vgrajenih kontrolnih elementov obrazca.

addText (string|int $name, $label=null, $cols, ?int $maxLength=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.

Vizualni značaj besedilnega polja lahko spremenite v vrste, kot so search, tel ali url z uporabo setHtmlType(), kot je prikazano v specifikaciji. Ne pozabite, da je spreminjanje tipa le vizualno in ne opravlja funkcij potrjevanja. Za vrsto url je primerno dodati posebno pravilo URL.

Za druge vhodne tipe, 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 preverjanje na strani strežnika. Tipa month in week še nista v celoti podprta v vseh brskalnikih.

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]);

Element se prikaže kot <input type="numeric">. Z uporabo metode setHtmlType() lahko tip spremenite v range za prikaz kot drsnik ali v text, če želite standardno besedilno polje brez posebnega obnašanja numeric.

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 brskalnik Chrome kot decimalno ločilo sprejemata tako vejico kot piko. Če želite, da je ta funkcionalnost na voljo v brskalniku Firefox, je priporočljivo nastaviti atribut lang bodisi za določen element bodisi za celotno stran, npr, <html lang="cs">.

addEmail (string|int $name, $label=null, int $maxLength=255): 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, $cols, ?int $maxLength=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).

Če obrazec pošiljate z metodo GET, lahko izberete bolj kompakten način prenosa podatkov, ki prihrani pri velikosti niza poizvedb. To aktivirate z nastavitvijo atributa HTML obrazca:

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

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, ?int $size=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.

Č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, ?int $size=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.

Č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.

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

$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.

Čeprav je element skrit, se je pomembno zavedati, da lahko napadalec še vedno spremeni ali ponaredi njegovo vrednost. Vedno temeljito preverite in potrdite vse prejete vrednosti na strani strežnika, 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', '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

Vhode lahko onemogočite z uporabo spletne strani setDisabled(). Onemogočenega vnosa uporabnik ne more urejati.

$form->addText('username', 'User name:')
	->setDisabled();

Brskalnik onemogočenih vnosov ne pošlje strežniku, zato jih ne boste našli v podatkih, ki jih vrne funkcija $form->getValues(). Če pa nastavite setOmitted(false), bo Nette v te podatke vključil njihovo privzeto vrednost.

Ko se pokliče setDisabled(), se vrednost vnosa zaradi varnostnih razlogov izbriše. Če nastavljate privzeto vrednost, je treba to storiti po njenem izklopu:

$form->addText('username', 'User name:')
	->setDisabled()
	->setDefaultValue($userName);

Alternativa onemogočenim vnosom so polja z atributom HTML readonly, ki jih brskalnik pošlje strežniku. Čeprav je polje samo berljivo, se je pomembno zavedati, da lahko napadalec še vedno spremeni ali ponaredi njegovo vrednost.

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.