Űrlap elemek

A standard űrlap elemek áttekintése.

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

Hozzáad egy egysoros szöveges mezőt (osztály: TextInput). Ha a felhasználó nem tölti ki a mezőt, üres stringet '' ad vissza, vagy a setNullable() segítségével beállítható, hogy null-t adjon vissza.

$form->addText('name', 'Név:')
	->setRequired()
	->setNullable();

Automatikusan validálja az UTF-8 kódolást, levágja a bal- és jobboldali szóközöket, és eltávolítja azokat az újsor karaktereket, amelyeket egy támadó küldhetett.

A maximális hosszúságot a setMaxLength() segítségével lehet korlátozni. A felhasználó által bevitt érték módosítását az addFilter() teszi lehetővé.

A setHtmlType() segítségével megváltoztatható a szöveges mező vizuális jellege olyan típusokra, mint a search, tel vagy url, lásd a specifikációt. Ne feledje, hogy a típusváltoztatás csak vizuális, és nem helyettesíti a validálási funkciót. Az url típushoz célszerű hozzáadni egy specifikus URL validálási szabályt.

Más beviteli típusokhoz, mint például a number, range, email, date, datetime-local, time és color, használjon specializált metódusokat, mint a addInteger, addFloat, addEmail addDate, addTime, addDateTime és addColor, amelyek biztosítják a szerveroldali validációt. A month és week típusok még nem támogatottak teljes mértékben minden böngészőben.

Az elemhez beállítható ún. empty-value, ami valami olyasmi, mint az alapértelmezett érték, de ha a felhasználó nem változtatja meg, az elem üres stringet vagy null-t ad vissza.

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

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

Hozzáad egy mezőt többsoros szöveg bevitelére (osztály: TextArea). Ha a felhasználó nem tölti ki a mezőt, üres stringet '' ad vissza, vagy a setNullable() segítségével beállítható, hogy null-t adjon vissza.

$form->addTextArea('note', 'Megjegyzés:')
	->addRule($form::MaxLength, 'A megjegyzés túl hosszú', 10000);

Automatikusan validálja az UTF-8 kódolást és normalizálja a sorelválasztókat \n-re. Ellentétben az egysoros beviteli mezővel, itt nem történik szóközök levágása.

A maximális hosszúságot a setMaxLength() segítségével lehet korlátozni. A felhasználó által bevitt érték módosítását az addFilter() teszi lehetővé. Beállítható ún. empty-value a setEmptyValue() segítségével.

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

Hozzáad egy mezőt egész számok bevitelére (osztály: TextInput). Vagy integert ad vissza, vagy null-t, ha a felhasználó nem ad meg semmit.

$form->addInteger('year', 'Év:')
	->addRule($form::Range, 'Az évnek %d és %d között kell lennie.', [1900, 2023]);

Az elem <input type="number">-ként jelenik meg. A setHtmlType() metódus használatával a típust range-re lehet változtatni a csúszka formájában történő megjelenítéshez, vagy text-re, ha a standard szöveges mezőt részesíti előnyben a number típus speciális viselkedése nélkül.

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

Hozzáad egy mezőt tizedes számok bevitelére (osztály: TextInput). Vagy floatot ad vissza, vagy null-t, ha a felhasználó nem ad meg semmit.

$form->addFloat('level', 'Szint:')
	->setDefaultValue(0)
	->addRule($form::Range, 'A szintnek %d és %d között kell lennie.', [0, 100]);

A Nette és a böngésző tizedes elválasztóként elfogadja mind a vesszőt, mind a pontot. Annak érdekében, hogy ez a funkcionalitás a Firefoxban is elérhető legyen, ajánlott beállítani a lang attribútumot vagy az adott elemre, vagy az egész oldalra, például <html lang="hu">.

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

Hozzáad egy mezőt e-mail cím bevitelére (osztály: TextInput). Ha a felhasználó nem tölti ki a mezőt, üres stringet '' ad vissza, vagy a setNullable() segítségével beállítható, hogy null-t adjon vissza.

$form->addEmail('email', 'E-mail:');

Ellenőrzi, hogy az érték érvényes e-mail cím-e. Nem ellenőrzi, hogy a domain valóban létezik-e, csak a szintaxist ellenőrzi. Automatikusan validálja az UTF-8 kódolást, levágja a bal- és jobboldali szóközöket.

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

Hozzáad egy mezőt jelszó bevitelére (osztály: TextInput).

$form->addPassword('password', 'Jelszó:')
	->setRequired()
	->addRule($form::MinLength, 'A jelszónak legalább %d karakter hosszúnak kell lennie', 8)
	->addRule($form::Pattern, 'Tartalmaznia kell számjegyet', '.*[0-9].*');

Az űrlap újramegjelenítésekor a mező üres lesz. Automatikusan validálja az UTF-8 kódolást, levágja a bal- és jobboldali szóközöket, és eltávolítja azokat az újsor karaktereket, amelyeket egy támadó küldhetett.

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

Hozzáad egy jelölőnégyzetet (osztály: Checkbox). Vagy true vagy false értéket ad vissza, attól függően, hogy be van-e jelölve.

$form->addCheckbox('agree', 'Elfogadom a feltételeket')
	->setRequired('El kell fogadni a feltételeket');

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

Hozzáad jelölőnégyzeteket több elem kiválasztásához (osztály: CheckboxList). A kiválasztott elemek kulcsainak tömbjét adja vissza. A getSelectedItems() metódus az értékeket adja vissza a kulcsok helyett.

$form->addCheckboxList('colors', 'Színek:', [
	'r' => 'piros',
	'g' => 'zöld',
	'b' => 'kék',
]);

A kínált elemek tömbjét harmadik paraméterként vagy a setItems() metódussal adjuk át.

A setDisabled(['r', 'g']) segítségével letilthatók az egyes elemek.

Az elem automatikusan ellenőrzi, hogy nem történt-e hamisítás, és hogy a kiválasztott elemek valóban a kínáltak közül valók-e, és nem voltak-e letiltva. A getRawValue() metódussal lekérhetők az elküldött elemek e fontos ellenőrzés nélkül.

Az alapértelmezett kiválasztott elemek beállításakor is ellenőrzi, hogy azok a kínáltak közül valók-e, különben kivételt dob. Ezt az ellenőrzést a checkDefaultValue(false) segítségével lehet kikapcsolni.

Ha az űrlapot GET metódussal küldi el, választhat egy kompaktabb adatátviteli módot, amely csökkenti a query string méretét. Ez az űrlap HTML attribútumának beállításával aktiválható:

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

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

Hozzáad rádiógombokat (osztály: RadioList). A kiválasztott elem kulcsát adja vissza, vagy null-t, ha a felhasználó nem választott semmit. A getSelectedItem() metódus az értéket adja vissza a kulcs helyett.

$sex = [
	'm' => 'férfi',
	'f' => 'nő',
];
$form->addRadioList('gender', 'Nem:', $sex);

A kínált elemek tömbjét harmadik paraméterként vagy a setItems() metódussal adjuk át.

A setDisabled(['m', 'f']) segítségével letilthatók az egyes elemek.

Az elem automatikusan ellenőrzi, hogy nem történt-e hamisítás, és hogy a kiválasztott elem valóban a kínáltak közül való-e, és nem volt-e letiltva. A getRawValue() metódussal lekérhető az elküldött elem e fontos ellenőrzés nélkül.

Az alapértelmezett kiválasztott elem beállításakor is ellenőrzi, hogy az a kínáltak közül való-e, különben kivételt dob. Ezt az ellenőrzést a checkDefaultValue(false) segítségével lehet kikapcsolni.

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

Hozzáad egy select boxot (osztály: SelectBox). A kiválasztott elem kulcsát adja vissza, vagy null-t, ha a felhasználó nem választott semmit. A getSelectedItem() metódus az értéket adja vissza a kulcs helyett.

$countries = [
	'CZ' => 'Cseh Köztársaság',
	'SK' => 'Szlovákia',
	'GB' => 'Nagy-Britannia',
];

$form->addSelect('country', 'Ország:', $countries)
	->setDefaultValue('SK');

A kínált elemek tömbjét harmadik paraméterként vagy a setItems() metódussal adjuk át. Az elemek lehetnek kétdimenziós tömbök is:

$countries = [
	'Európa' => [
		'CZ' => 'Cseh Köztársaság',
		'SK' => 'Szlovákia',
		'GB' => 'Nagy-Britannia',
	],
	'CA' => 'Kanada',
	'US' => 'USA',
	'?'  => 'más',
];

A select boxoknál gyakran az első elemnek speciális jelentése van, felhívásként szolgál. Ilyen elem hozzáadására a setPrompt() metódus szolgál.

$form->addSelect('country', 'Ország:', $countries)
	->setPrompt('Válasszon országot');

A setDisabled(['CZ', 'SK']) segítségével letilthatók az egyes elemek.

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

Hozzáad egy select boxot több elem kiválasztásához (osztály: MultiSelectBox). A kiválasztott elemek kulcsainak tömbjét adja vissza. A getSelectedItems() metódus az értékeket adja vissza a kulcsok helyett.

$form->addMultiSelect('countries', 'Országok:', $countries);

A kínált elemek tömbjét harmadik paraméterként vagy a setItems() metódussal adjuk át. Az elemek lehetnek kétdimenziós tömbök is.

A setDisabled(['CZ', 'SK']) segítségével letilthatók az egyes elemek.

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

Hozzáad egy mezőt fájl feltöltéséhez (osztály: UploadControl). Egy FileUpload objektumot ad vissza, még akkor is, ha a felhasználó nem küldött fájlt, amit a FileUpload::hasFile() metódussal lehet ellenőrizni.

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Az avatarnak JPEG, PNG, GIF, WebP vagy AVIF formátumúnak kell lennie.')
	->addRule($form::MaxFileSize, 'A maximális méret 1 MB.', 1024 * 1024);

Ha a fájl feltöltése nem sikerül megfelelően, az űrlap nem kerül sikeresen elküldésre, és hiba jelenik meg. Vagyis sikeres elküldés esetén nem szükséges ellenőrizni a FileUpload::isOk() metódust.

Soha ne bízzon a FileUpload::getName() metódus által visszaadott eredeti fájlnévben, a kliens rosszindulatú fájlnevet küldhetett azzal a szándékkal, hogy kárt okozzon vagy feltörje az alkalmazását.

A MimeType és Image szabályok a fájl aláírása alapján észlelik a kívánt típust, és nem ellenőrzik annak integritását. Azt, hogy a kép nem sérült-e, például a betöltésének megkísérlésével lehet megállapítani.

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

Hozzáad egy mezőt több fájl egyidejű feltöltéséhez (osztály: UploadControl). FileUpload objektumok tömbjét adja vissza. A FileUpload::hasFile() metódus mindegyiknél true-t fog visszaadni.

$form->addMultiUpload('files', 'Fájlok:')
	->addRule($form::MaxLength, 'Legfeljebb %d fájlt lehet feltölteni', 10);

Ha valamelyik fájl feltöltése nem sikerül megfelelően, az űrlap nem kerül sikeresen elküldésre, és hiba jelenik meg. Vagyis sikeres elküldés esetén nem szükséges ellenőrizni a FileUpload::isOk() metódust.

Soha ne bízzon a FileUpload::getName() metódus által visszaadott eredeti fájlnevekben, a kliens rosszindulatú fájlnevet küldhetett azzal a szándékkal, hogy kárt okozzon vagy feltörje az alkalmazását.

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

Hozzáad egy mezőt, amely lehetővé teszi a felhasználó számára, hogy könnyen megadjon egy dátumot, amely évből, hónapból és napból áll (osztály: DateTimeControl).

Alapértelmezett értékként elfogadja vagy a DateTimeInterface interfészt implementáló objektumokat, egy időt tartalmazó stringet, vagy egy UNIX timestamp-et képviselő számot. Ugyanez vonatkozik a Min, Max vagy Range szabályok argumentumaira is, amelyek meghatározzák a minimális és maximális megengedett dátumot.

$form->addDate('date', 'Dátum:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'A dátumnak legalább egy hónaposnak kell lennie.', new DateTime('-1 month'));

Alapértelmezés szerint DateTimeImmutable objektumot ad vissza, a setFormat() metódussal megadhatja a szöveges formátumot vagy a timestamp-et:

$form->addDate('date', 'Dátum:')
	->setFormat('Y-m-d');

addTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Hozzáad egy mezőt, amely lehetővé teszi a felhasználó számára, hogy könnyen megadjon egy időt, amely órákból, percekből és opcionálisan másodpercekből áll (osztály: DateTimeControl).

Alapértelmezett értékként elfogadja vagy a DateTimeInterface interfészt implementáló objektumokat, egy időt tartalmazó stringet, vagy egy UNIX timestamp-et képviselő számot. Ezekből a bemenetekből csak az időinformáció kerül felhasználásra, a dátum figyelmen kívül marad. Ugyanez vonatkozik a Min, Max vagy Range szabályok argumentumaira is, amelyek meghatározzák a minimális és maximális megengedett időt. Ha a beállított minimális érték magasabb, mint a maximális, akkor egy éjfélen átnyúló időtartomány jön létre.

$form->addTime('time', 'Idő:', withSeconds: true)
	->addRule($form::Range, 'Az időnek %d és %d között kell lennie.', ['12:30', '13:30']);

Alapértelmezés szerint DateTimeImmutable objektumot ad vissza (az 1. év január 1-jei dátummal), a setFormat() metódussal megadhatja a szöveges formátumot:

$form->addTime('time', 'Idő:')
	->setFormat('H:i');

addDateTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Hozzáad egy mezőt, amely lehetővé teszi a felhasználó számára, hogy könnyen megadjon egy dátumot és időt, amely évből, hónapból, napból, órákból, percekből és opcionálisan másodpercekből áll (osztály: DateTimeControl).

Alapértelmezett értékként elfogadja vagy a DateTimeInterface interfészt implementáló objektumokat, egy időt tartalmazó stringet, vagy egy UNIX timestamp-et képviselő számot. Ugyanez vonatkozik a Min, Max vagy Range szabályok argumentumaira is, amelyek meghatározzák a minimális és maximális megengedett dátumot.

$form->addDateTime('datetime', 'Dátum és idő:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'A dátumnak legalább egy hónaposnak kell lennie.', new DateTime('-1 month'));

Alapértelmezés szerint DateTimeImmutable objektumot ad vissza, a setFormat() metódussal megadhatja a szöveges formátumot vagy a timestamp-et:

$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);

addColor (string|int $name, $label=null): ColorPicker

Hozzáad egy mezőt színválasztáshoz (osztály: ColorPicker). A szín egy #rrggbb formátumú string. Ha a felhasználó nem választ, a fekete szín #000000 kerül visszaadásra.

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

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

Hozzáad egy rejtett mezőt (osztály: HiddenField).

$form->addHidden('userid');

A setNullable() segítségével beállítható, hogy null-t adjon vissza üres string helyett. Az elküldött érték módosítását az addFilter() teszi lehetővé.

Bár az elem rejtett, fontos tudatosítani, hogy az értékét egy támadó továbbra is módosíthatja vagy hamisíthatja. Mindig alaposan ellenőrizze és validálja az összes fogadott értéket a szerveroldalon, hogy megelőzze az adatmanipulációval kapcsolatos biztonsági kockázatokat.

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

Hozzáad egy küldés gombot (osztály: SubmitButton).

$form->addSubmit('submit', 'Küldés');

Az űrlapon több küldés gomb is lehet:

$form->addSubmit('register', 'Regisztráció');
$form->addSubmit('cancel', 'Mégse');

Annak megállapításához, hogy melyikre kattintottak, használja a következőt:

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

Ha nem szeretné az egész űrlapot validálni a gomb megnyomásakor (például a Mégse vagy Előnézet gomboknál), használja a setValidationScope() metódust.

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

Hozzáad egy gombot (osztály: Button), amelynek nincs küldési funkciója. Használható tehát valamilyen más funkcióra, pl. JavaScript függvény meghívására kattintáskor.

$form->addButton('raise', 'Fizetésemelés')
	->setHtmlAttribute('onclick', 'raiseSalary()');

addImageButton (string|int $name, ?string $src=null, ?string $alt=null): ImageButton

Hozzáad egy kép formájú küldés gombot (osztály: ImageButton).

$form->addImageButton('submit', '/útvonal/a/képhez.png');

Több küldés gomb használatakor a $form['submit']->isSubmittedBy() segítségével megállapítható, hogy melyikre kattintottak.

addContainer (string|int $name): Container

Hozzáad egy alűrlapot (osztály: Container), vagyis egy konténert, amelybe ugyanúgy lehet további elemeket hozzáadni, mint ahogy az űrlaphoz adjuk őket. Működnek a setDefaults() vagy getValues() metódusok is.

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Neved:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Neved:');
$sub2->addEmail('email', 'Email:');

Az elküldött adatok ezután többdimenziós struktúraként kerülnek visszaadásra:

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

Beállítások áttekintése

Minden elemnél meghívhatjuk a következő metódusokat (teljes áttekintés az API dokumentációban):

`setDefaultValue($value)`	beállítja az alapértelmezett értéket
`getValue()`	lekéri az aktuális értéket
`setOmitted()`	Érték kihagyása
`setDisabled()`	Elemek letiltása

Megjelenítés:

`setCaption($caption)`	megváltoztatja az elem címkéjét
`setTranslator($translator)`	beállítja a fordítót
`setHtmlAttribute($name, $value)`	beállítja az elem HTML attribútumát
`setHtmlId($id)`	beállítja a HTML `id` attribútumot
`setHtmlType($type)`	beállítja a HTML `type` attribútumot
`setHtmlName($name)`	beállítja a HTML `name` attribútumot
`setOption($key, $value)`	megjelenítési beállítások

Validáció:

`setRequired()`	kötelező elem
`addRule()`	beállítja az érvényesítési szabályt
`addCondition()`, `addConditionOn()`	beállítja az érvényesítési feltételt
`addError($message)`	hibaüzenet átadása

Az addText(), addPassword(), addTextArea(), addEmail(), addInteger() elemeknél a következő metódusokat lehet meghívni:

`setNullable()`	beállítja, hogy a getValue() `null`-t adjon-e vissza üres string helyett
`setEmptyValue($value)`	beállít egy speciális értéket, amely üres stringnek minősül
`setMaxLength($length)`	beállítja a megengedett karakterek maximális számát
`addFilter($filter)`	bemenet módosítása

Érték kihagyása

Ha nem érdekel minket a felhasználó által kitöltött érték, a setOmitted() segítségével kihagyhatjuk a $form->getValues() metódus eredményéből vagy a handlereknek átadott adatokból. Ez hasznos lehet különböző ellenőrző jelszavaknál, antispam elemeknél stb.

$form->addPassword('passwordVerify', 'Jelszó újra:')
	->setRequired('Kérjük, adja meg a jelszót újra az ellenőrzéshez')
	->addRule($form::Equal, 'A jelszavak nem egyeznek', $form['password'])
	->setOmitted();

Elemek letiltása

Az elemeket a setDisabled() segítségével lehet letiltani. Egy ilyen elemet a felhasználó nem tud szerkeszteni.

$form->addText('username', 'Felhasználónév:')
	->setDisabled();

A letiltott elemeket a böngésző egyáltalán nem küldi el a szerverre, tehát nem is találja meg őket a $form->getValues() függvény által visszaadott adatokban. Ha azonban beállítja a setOmitted(false) értéket, a Nette ezekbe az adatokba belefoglalja az alapértelmezett értéküket.

A setDisabled() hívásakor biztonsági okokból törlődik az elem értéke. Ha alapértelmezett értéket állít be, azt a letiltás után kell megtenni:

$form->addText('username', 'Felhasználónév:')
	->setDisabled()
	->setDefaultValue($userName);

A letiltott elemek alternatívája a readonly HTML attribútummal rendelkező elemek, amelyeket a böngésző elküld a szerverre. Bár az elem csak olvasható, fontos tudatosítani, hogy az értékét egy támadó továbbra is módosíthatja vagy hamisíthatja.

Egyéni elemek

A beépített űrlap elemek széles skálája mellett egyéni elemeket is hozzáadhat az űrlaphoz a következő módon:

$form->addComponent(new DateInput('Dátum:'), 'date');
// alternatív szintaxis: $form['date'] = new DateInput('Dátum:');

Az űrlap a Container osztály leszármazottja, az egyes elemek pedig a Component leszármazottai.

Létezik egy módszer új űrlap metódusok definiálására, amelyek egyéni elemek hozzáadására szolgálnak (pl. $form->addZip()). Ezek az ún. extension methods. Hátrányuk, hogy a szerkesztőkben nem fog működni rájuk a kódkiegészítés.

use Nette\Forms\Container;

// hozzáadjuk az addZip(string $name, ?string $label = null) metódust
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'Legalább 5 számjegy', '[0-9]{5}');
});

// használat
$form->addZip('zip', 'Irányítószám:');

Alacsony szintű elemek

Használhatunk olyan elemeket is, amelyeket csak a sablonban írunk le, és nem adjuk hozzá az űrlaphoz valamelyik $form->addXyz() metódussal. Ha például adatbázisból listázunk rekordokat, és előre nem tudjuk, hány lesz belőlük és milyen ID-jük lesz, és minden sornál szeretnénk egy checkboxot vagy radio buttont megjeleníteni, elég azt a sablonban kódolni:

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

És elküldés után lekérjük az értéket:

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

ahol az első paraméter az elem típusa (DataFile a type=file-hoz, DataLine az egysoros bemenetekhez, mint text, password, email stb., és DataText az összes többihez), a második paraméter sel[] pedig a HTML name attribútumnak felel meg. Az elem típusát kombinálhatjuk a DataKeys értékkel, amely megőrzi az elemek kulcsait. Ez különösen hasznos a select, radioList és checkboxList esetén.

Lényeges, hogy a getHttpData() szanitizált értéket ad vissza, ebben az esetben ez mindig érvényes UTF-8 stringek tömbje lesz, függetlenül attól, hogy a támadó mit próbált a szervernek becsempészni. Ez hasonló a közvetlen $_POST vagy $_GET kezeléséhez, azzal a lényeges különbséggel, hogy mindig tiszta adatokat ad vissza, ahogy azt a standard Nette űrlap elemeknél megszokhattuk.