Nyomtatvány vezérlők

A beépített űrlapvezérlők áttekintése.

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

Egysoros szövegmező hozzáadása ( TextInput osztály). Ha a felhasználó nem tölti ki a mezőt, akkor egy üres karakterláncot ad vissza '', vagy a setNullable() segítségével megváltoztatja, hogy null adjon vissza.

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

Automatikusan érvényesíti az UTF-8 szabványt, levágja a bal és jobb oldali fehérjeleket, és eltávolítja a támadó által küldhető sortöréseket.

A maximális hossz a setMaxLength() segítségével korlátozható. Az addFilter() lehetővé teszi a felhasználó által megadott érték megváltoztatását.

A setHtmlType() segítségével a search, tel, url, range, date, datetime-local, month, time, week, color beviteli elem karakterét módosíthatja. A number és email típusok helyett az addInteger és az addEmail típusok használatát javasoljuk, amelyek szerveroldali érvényesítést biztosítanak.

$form->addText('color', 'Choose color:')
	->setHtmlType('color')
	->addRule($form::Pattern, 'invalid value', '[0-9a-f]{6}');

Az elemhez beállítható az úgynevezett üres-érték, ami valami olyasmi, mint az alapértelmezett érték, de ha a felhasználó nem írja felül, akkor üres stringet vagy null ad vissza.

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

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

Hozzáad egy többsoros szövegmezőt ( TextArea osztály). Ha a felhasználó nem tölti ki a mezőt, akkor egy üres karakterláncot ad vissza '', vagy a setNullable() segítségével megváltoztatja, hogy null adjon vissza.

$form->addTextArea('note', 'Note:')
	->addRule($form::MaxLength, 'Your note is way too long', 10000);

Automatikusan érvényesíti az UTF-8 formátumot és normalizálja a sortöréseket a \n. Az egysoros beviteli mezővel ellentétben nem vágja le a szóközöket.

A maximális hossz a setMaxLength() segítségével korlátozható. Az addFilter() lehetővé teszi a felhasználó által beírt érték megváltoztatását. Az úgynevezett üres értéket a setEmptyValue() segítségével állíthatja be.

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

Egész számok beviteli mezőjének hozzáadása ( TextInput osztály). Egész számot vagy a null értéket adja vissza, ha a felhasználó nem ad meg semmit.

$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

E-mail cím mező hozzáadása érvényességi ellenőrzéssel ( TextInput osztály). Ha a felhasználó nem tölti ki a mezőt, akkor egy üres karakterláncot ad vissza '', vagy a setNullable() segítségével megváltoztatja, hogy null adjon vissza.

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

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 szintaxisát ellenőrzi. Automatikusan érvényesíti az UTF-8 szabványt, a bal és jobb oldali fehérjeleket levágja.

A maximális hossz a setMaxLength() segítségével korlátozható. Az addFilter() lehetővé teszi a felhasználó által megadott érték megváltoztatását. Az úgynevezett üres értéket a setEmptyValue() segítségével állíthatja be.

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

Jelszó mező hozzáadása ( TextInput osztály).

$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].*');

Amikor újra elküldi az űrlapot, a bevitel üres lesz. Automatikusan érvényesíti az UTF-8 kódot, levágja a bal és jobb oldali fehérjeleket, és eltávolítja a támadó által küldhető sortöréseket.

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

Hozzáad egy jelölőnégyzetet ( Checkbox osztály). A mező a true vagy a false címet adja vissza, attól függően, hogy be van-e jelölve.

$form->addCheckbox('agree', 'I agree with terms')
	->setRequired('You must agree with our terms');

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

Több elem kiválasztására szolgáló jelölőnégyzetek listájának hozzáadása ( CheckboxList osztály). Visszaadja a kiválasztott elemek kulcsainak tömbjét. A getSelectedItems() módszer kulcsok helyett értékeket ad vissza.

$form->addCheckboxList('colors', 'Colors:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);

Az elemek tömbjét harmadik paraméterként, vagy a setItems() módszerrel adjuk át.

Használhatja a setDisabled(['r', 'g']) az egyes elemek letiltására.

Az elem automatikusan ellenőrzi, hogy nem történt-e hamisítás, és hogy a kiválasztott elemek valóban a felkínált elemek közé tartoznak-e, és nem lettek-e letiltva. A getRawValue() módszerrel a beküldött elemek e fontos ellenőrzés nélkül is lekérdezhetők.

Alapértelmezett értékek beállítása esetén azt is ellenőrzi, hogy azok a felkínált elemek közé tartoznak-e, ellenkező esetben kivételt dob. Ez az ellenőrzés kikapcsolható a checkDefaultValue(false) segítségével.

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

Rádiógombok hozzáadása ( RadioList osztály). Visszaadja a kiválasztott elem kulcsát, vagy null, ha a felhasználó nem választott ki semmit. A getSelectedItem() metódus kulcs helyett értéket ad vissza.

$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);

Az elemek tömbjét harmadik paraméterként adjuk át, vagy a setItems() módszerrel.

Használhatja a setDisabled(['m']) az egyes elemek letiltására.

Az elem automatikusan ellenőrzi, hogy nem történt-e hamisítás, és hogy a kiválasztott elem valóban a felkínált elemek egyike-e, és nem lett-e letiltva. A getRawValue() módszerrel a beküldött elemet e fontos ellenőrzés nélkül is lekérdezheti.

Alapértelmezett érték beállítása esetén azt is ellenőrzi, hogy a felajánlott elemek egyike-e, ellenkező esetben kivételt dob. Ez az ellenőrzés kikapcsolható a checkDefaultValue(false) segítségével.

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

Kijelölő doboz hozzáadása ( SelectBox osztály). Visszaadja a kiválasztott elem kulcsát, vagy null, ha a felhasználó nem választott ki semmit. A getSelectedItem() metódus kulcs helyett értéket ad vissza.

$countries = [
	'CZ' => 'Czech republic',
	'SK' => 'Slovakia',
	'GB' => 'United Kingdom',
];

$form->addSelect('country', 'Country:', $countries)
	->setDefaultValue('SK');

Az elemek tömbjét harmadik paraméterként adjuk át, vagy a setItems() módszerrel. Az elemek tömbje lehet kétdimenziós is:

$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];

A kiválasztó dobozok esetében az első elemnek gyakran különleges jelentősége van, ez a call-to-action funkciót látja el. Ilyen bejegyzés hozzáadásához használja a setPrompt() módszert.

$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');

Használhatja a setDisabled(['CZ', 'SK']) az egyes elemek letiltására.

Az elem automatikusan ellenőrzi, hogy nem történt-e hamisítás, és hogy a kiválasztott elem valóban a felkínált elemek egyike-e, és nem lett-e letiltva. A getRawValue() módszerrel a beküldött elemet e fontos ellenőrzés nélkül is lekérdezheti.

Alapértelmezett érték beállítása esetén azt is ellenőrzi, hogy a felajánlott elemek egyike-e, ellenkező esetben kivételt dob. Ez az ellenőrzés kikapcsolható a checkDefaultValue(false) segítségével.

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

Hozzáadja a többválasztós kiválasztó dobozt ( MultiSelectBox osztály). Visszaadja a kiválasztott elemek kulcsainak tömbjét. A getSelectedItems() módszer kulcsok helyett értékeket ad vissza.

$form->addMultiSelect('countries', 'Countries:', $countries);

Az elemek tömbjét harmadik paraméterként, vagy a setItems() módszerrel adjuk át. Az elemek tömbje lehet kétdimenziós is.

Használhatja a setDisabled(['CZ', 'SK']) az egyes elemek letiltására.

Az elem automatikusan ellenőrzi, hogy nem történt-e hamisítás, és hogy a kiválasztott elemek valóban a felkínált elemek közé tartoznak-e, és nem lettek-e letiltva. A getRawValue() módszerrel a beküldött elemek e fontos ellenőrzés nélkül is lekérdezhetők.

Alapértelmezett értékek beállítása esetén azt is ellenőrzi, hogy azok a felkínált elemek közé tartoznak-e, ellenkező esetben kivételt dob. Ez az ellenőrzés kikapcsolható a checkDefaultValue(false) segítségével.

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

Fájlfeltöltő mező hozzáadása ( UploadControl osztály). Visszaadja a FileUpload objektumot, még akkor is, ha a felhasználó nem töltött fel fájlt, amit a FileUpload::hasFile() metódussal lehet kideríteni.

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

Ha a fájl feltöltése nem volt megfelelő, akkor az űrlap nem lett sikeresen elküldve, és hibaüzenet jelenik meg. Vagyis nem szükséges a FileUpload::isOk() metódus ellenőrzésére.

Ne bízzon a FileUpload::getName() módszer által visszaküldött eredeti fájlnévben, az ügyfél rosszindulatú fájlnevet küldhet azzal a szándékkal, hogy megrongálja vagy feltörje az alkalmazást.

A MimeType és a Image szabályok az aláírás alapján ismerik fel a kívánt fájl- vagy képtípust. A teljes fájl sértetlenségét nem ellenőrzik. Azt, hogy egy kép nem sérült-e, például a betöltési próbálkozással állapíthatja meg.

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

Több fájlfeltöltő mező hozzáadása ( UploadControl osztály). Visszaadja a FileUpload objektumok tömbjét. A FileUpload::hasFile() metódus mindegyikükhöz a true metódust adja vissza.

$form->addMultiUpload('files', 'Files:')
	->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);

Ha az egyik fájl feltöltése nem sikerül megfelelően, akkor az űrlapot nem sikeresen küldték el, és hibaüzenet jelenik meg. Vagyis nem szükséges ellenőrizni a FileUpload::isOk() metódust.

Ne bízzon a FileUpload::getName() módszer által visszaküldött eredeti fájlnevekben, egy ügyfél rosszindulatú fájlnevet küldhet azzal a szándékkal, hogy megrongálja vagy feltörje az alkalmazást.

A MimeType és a Image szabályok az aláírás alapján ismerik fel a kívánt fájl- vagy képtípust. A teljes fájl sértetlenségét nem ellenőrzik. Azt, hogy egy kép nem sérült-e, például a betöltési próbálkozással állapíthatja meg.

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

Rejtett mező hozzáadása ( HiddenField osztály).

$form->addHidden('userid');

Használja a setNullable() címet, hogy üres karakterlánc helyett null -t adjon vissza. Az addFilter() lehetővé teszi a beküldött érték megváltoztatását.

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

Hozzáadja a submit gombot ( SubmitButton osztály).

$form->addSubmit('submit', 'Register');

Lehetséges, hogy egynél több submit gomb legyen az űrlapon:

$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');

Ahhoz, hogy megtudja, melyikre kattintottak, használja a következőt:

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

Ha nem akarja érvényesíteni az űrlapot, amikor egy beküldő gombot megnyomnak (például a Cancel vagy Preview gombokat), akkor a setValidationScope() segítségével kikapcsolhatja.

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

Hozzáad egy gombot ( Button osztály) submit funkció nélkül. Hasznos más funkciók id-hez kötéséhez, például egy JavaScript művelethez.

$form->addButton('raise', 'Raise salary')
	->setHtmlAttribute('onclick', 'raiseSalary()');

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

Hozzáadja a submit gombot kép formájában ( ImageButton osztály).

$form->addImageButton('submit', '/path/to/image');

Több submit gomb használata esetén megtudhatja, hogy melyikre kattintott a $form['submit']->isSubmittedBy().

addContainer(string|int $name): Container

Hozzáad egy al-űrlapot ( Container osztály), vagy konténert, amely ugyanúgy kezelhető, mint egy űrlap. Ez azt jelenti, hogy használhatja az olyan módszereket, mint a setDefaults() vagy a 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:');

Az elküldött adatokat ezután többdimenziós struktúraként adja vissza:

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

A beállítások áttekintése

Minden elemhez a következő metódusokat hívhatjuk meg (a teljes áttekintésért lásd az API dokumentációt ):

Renderelés:

Érvényesítés:

A következő metódusok hívhatók a addText(), addPassword(), addTextArea(), addEmail(), addInteger() elemekhez:

Kihagyott értékek

Ha nem érdekel a felhasználó által megadott érték, a setOmitted() segítségével kihagyhatjuk azt a $form->getValues​() metódus által szolgáltatott vagy a kezelőknek átadott eredményből. Ez alkalmas különböző jelszavak ellenőrzésére, spamellenes mezőkhöz stb.

$form->addPassword('passwordVerify', 'Password again:')
	->setRequired('Fill your password again to check for typo')
	->addRule($form::Equal, 'Password mismatch', $form['password'])
	->setOmitted();

Bemenetek letiltása

Egy bemenet letiltásához hívja a setDisabled() címet. Az ilyen mezőt a felhasználó nem szerkesztheti.

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

Vegye figyelembe, hogy a böngésző egyáltalán nem küldi el a letiltott mezőket a szerverre, így a $form->getValues() függvény által visszaküldött adatokban sem fogja megtalálni őket.

Ha alapértelmezett értéket állít be egy mezőhöz, akkor ezt csak a mező letiltása után szabad megtennie:

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

Egyéni vezérlők

A beépített űrlapvezérlők széles skálája mellett egyéni vezérlőket is hozzáadhat az űrlaphoz az alábbiak szerint:

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

A form a Container osztály leszármazottja, az elemek pedig a Component osztály leszármazottai.

Van lehetőség új űrlapmódszerek definiálására az egyéni elemek hozzáadásához (pl. $form->addZip()). Ezek az úgynevezett kiterjesztési metódusok. Hátrányuk, hogy a szerkesztőkben a kódsegédletek nem működnek ezeknél.

use Nette\Forms\Container;

// adds method 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, 'Legalább 5 szám', '[0-9]{5}');
});

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

Alacsony szintű mezők

Egy elem hozzáadásához az űrlaphoz nem kell meghívni a $form->addXyz() címet. Az űrlapelemeket ehelyett kizárólag sablonokban lehet bevezetni. Ez akkor hasznos, ha például dinamikus elemeket kell létrehozni:

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

A beküldés után lekérdezheti az értékeket:

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

Az első paraméterben megadhatja az elem típusát (DataFile a type=file, DataLine az egysoros bemenetekhez, mint a text, password vagy email és DataText a többi). A második paraméter megfelel a name HTML-attribútumnak. Ha meg kell őrizni a kulcsokat, akkor az első paramétert kombinálhatja a DataKeys paraméterrel. Ez a select, radioList vagy checkboxList esetében hasznos.

A getHttpData() szanált bemenetet ad vissza. Ebben az esetben mindig érvényes UTF-8-as karakterláncok tömbje lesz, függetlenül attól, hogy az űrlap által küldött támadó mit küldött. Ez egy alternatívája a $_POST vagy $_GET közvetlen munkájának, ha biztonságos adatokat szeretne kapni.