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 bemeneti elem karakterét search, tel, url, range, month, week vagy colorkarakterre változtathatja. Más típusokhoz, mint például a number, email, date, datetime-local és time, külön metódusok állnak rendelkezésre: addInteger, addFloat, addEmail, addDate, addTime és addDateTime, amelyek szerveroldali érvényesítéssel rendelkeznek.

$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('year', 'Év:')
	->addRule($form::Range, 'Az évnek a %d és %d közötti tartományban kell lennie.', [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('szint', 'Szint:')
	->setDefaultValue(0)
->addRule($form::Range, 'A szintnek a %d és %d közötti tartományban kell lennie.', [0, 100 |0, 100]);

A Nette és a Chrome elfogadja a vesszőt és a pontot is tizedesválasztóként. Ahhoz, hogy a Firefox is elfogadja a vesszőt, be kell állítania a megfelelő nyelvet a lang HTML-attribútumban, vagy közvetlenül ehhez az elemhez, vagy bármelyik szülőelemhez, pl. <html lang="cs">.

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.

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.

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.

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

Hozzáad egy mezőt, amely lehetővé teszi a felhasználó számára, hogy egyszerűen beírjon egy dátumot, amely évből, hónapból és napból áll ( DateTimeControl osztály).

Alapértelmezett értékként elfogadja a DateTimeInterface objektumokat megvalósító objektumokat, az időt tartalmazó karakterláncot, vagy egy UNIX időbélyeget reprezentáló számot. Ugyanez vonatkozik a Min, Max vagy Range szabály argumentumaira is, amelyek a minimális és maximálisan megengedett dátumot határozzák meg.

$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Alapértelmezés szerint egy DateTimeImmutable objektumot ad vissza. A setFormat() módszerrel szöveges formátumot vagy időbélyeget adhat meg:

$form->addDate('date', 'Date:')
	->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 egyszerűen beírja az órákból, percekből és opcionálisan másodpercekből álló időt ( DateTimeControl osztály).

Alapértelmezett értékként elfogadja a DateTimeInterface objektumokat megvalósító objektumokat, az időt tartalmazó karakterláncot vagy egy UNIX időbélyeget jelentő számot. Csak az ezekből a bemenetekből származó időinformáció kerül felhasználásra; a dátumot figyelmen kívül hagyja. Ugyanez vonatkozik a Min, Max vagy Range szabály argumentumaira is, amelyek a minimális és maximális megengedett időt határozzák meg. Ha a beállított minimális érték nagyobb, mint a maximális, akkor egy éjfélig tartó időtartomány jön létre.

$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);

Alapértelmezés szerint egy DateTimeImmutable objektumot ad vissza (január 1-jei dátummal, 1. év). A setFormat() módszerrel szöveges formátumot adhat meg:

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

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

Hozzáad egy olyan mezőt, amely lehetővé teszi a felhasználó számára, hogy egyszerűen beírja a dátumot és az időt, amely évből, hónapból, napból, órából, percből és opcionálisan másodpercekből áll ( DateTimeControl osztály).

Alapértelmezett értékként elfogadja a DateTimeInterface objektumokat megvalósító objektumokat, egy karakterláncot az idővel, vagy egy UNIX időbélyeget reprezentáló számot. Ugyanez vonatkozik a Min, Max vagy Range szabály argumentumaira is, amelyek a minimális és maximálisan megengedett dátumot határozzák meg.

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

Alapértelmezés szerint egy DateTimeImmutable objektumot ad vissza. A setFormat() módszerrel szöveges formátumot vagy időbélyeget adhat meg:

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

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

Hozzáad egy színválasztó mezőt ( ColorPicker osztály). A szín egy karakterlánc a #rrggbb formátumban. Ha a felhasználó nem választ, a visszaküldött alapértelmezett szín a fekete #000000.

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

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.

Bár az elem rejtve van, fontos tudatosítani, hogy az értékét egy támadó még mindig módosíthatja vagy meghamisíthatja. Az adatmanipulációval kapcsolatos biztonsági kockázatok megelőzése érdekében mindig alaposan ellenőrizze és validálja az összes kapott értéket a kiszolgálói oldalon.

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

`setDefaultValue($value)`	az alapértelmezett érték beállítása
`getValue()`	aktuális érték lekérése
`setOmitted()`	kihagyott értékek
`setDisabled()`	bemenetek letiltása

Renderelés:

`setCaption($caption)`	az elem feliratának módosítása
`setTranslator($translator)`	fordító beállítása
`setHtmlAttribute($name, $value)`	beállítja az elem HTML-attribútumát.
`setHtmlId($id)`	beállítja a HTML-attribútumot `id`
`setHtmlType($type)`	HTML-attribútum beállítása `type`
`setHtmlName($name)`	HTML-attribútum beállítása `name`
`setOption($key, $value)`	beállítja a renderelési adatokat

Érvényesítés:

`setRequired()`	kötelező mező
`addRule()`	érvényesítési szabály beállítása
`addCondition()`, `addConditionOn()`	érvényesítési feltétel beállítása
`addError($message)`	hibaüzenet átadása

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

`setNullable()`	beállítja, hogy a getValue() az üres karakterlánc helyett a `null` értéket adja-e vissza.
`setEmptyValue($value)`	beállítja a speciális értéket, amelyet üres karakterláncként kezel.
`setMaxLength($length)`	beállítja a megengedett karakterek maximális számát.
`addFilter($filter)`	bemeneti értékek módosítása

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

A bemeneteket a setDisabled() segítségével lehet letiltani. A letiltott bemenetet a felhasználó nem tudja szerkeszteni.

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

A letiltott bemeneteket a böngésző nem küldi el a kiszolgálónak, így a $form->getValues() funkció által visszaküldött adatokban sem találja meg őket. Ha azonban beállítja a setOmitted(false), a Nette az alapértelmezett értéküket is tartalmazza ezekben az adatokban.

A setDisabled() meghívásakor a bemenet értéke biztonsági okokból törlődik. Ha alapértelmezett értéket állít be, akkor azt a deaktiválás után kell megtennie:

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

A letiltott bejegyzések alternatívája a HTML readonly attribútummal rendelkező mezők, amelyeket a böngésző küld a kiszolgálónak. Bár a mező csak olvasható, fontos tudatosítani, hogy az értékét egy támadó még mindig módosíthatja vagy meghamisíthatja.

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.