Önállóan használt űrlapok
*************************

.[perex]
A Nette Forms jelentősen megkönnyíti a webes űrlapok létrehozását és feldolgozását. Alkalmazásaiban teljesen önállóan, a keretrendszer többi része nélkül is használhatja őket, amit ebben a fejezetben bemutatunk.

Ha azonban Nette alkalmazást és prezentereket használ, akkor van egy útmutató az Ön számára: [Forms in presenters |in-presenter].


Első űrlap .[#toc-first-form]
=============================

Megpróbálunk írni egy egyszerű regisztrációs űrlapot. A kódja így fog kinézni ("teljes kód":https://gist.github.com/dg/370a7e3094d9ba9a9e913b8e2a2dc851):

```php
use Nette\Forms\Form;

$form = new Form;
$form->addText('name', 'Name:');
$form->addPassword('password', 'Password:');
$form->addSubmit('send', 'Sign up');
```

És rendereljük le:

```php
$form->render();
```

Az eredménynek így kell kinéznie:

[* form-en.webp *]

Az űrlap a `Nette\Forms\Form` osztály objektuma (a `Nette\Application\UI\Form` osztály a prezenterekben használatos). Hozzáadtuk a vezérlőelemeket név, jelszó és küldés gomb.

Most újraélesztjük az űrlapot. A `$form->isSuccess()` megkérdezésével megtudjuk, hogy az űrlapot elküldtük-e, és hogy érvényesen töltöttük-e ki. Ha igen, akkor ki fogjuk dobni az adatokat. Az űrlap definíciója után hozzáadjuk:

```php
if ($form->isSuccess()) {
	echo 'Az űrlapot helyesen töltöttük ki és küldtük el';
	$data = $form->getValues();
	// $data->name tartalmazza a nevet
	// $data->password tartalmazza a jelszót
	var_dump($data);
}
```

A `getValues()` metódus az elküldött adatokat egy [ArrayHash |utils:arrays#ArrayHash] objektum formájában adja vissza. [Később |#Mapping to Classes] megmutatjuk, hogyan lehet ezt megváltoztatni. A `$data` változó tartalmazza a `name` és `password` kulcsokat a felhasználó által megadott adatokkal.

Általában az adatokat közvetlenül küldjük el további feldolgozásra, ami lehet például az adatbázisba való beillesztés. A feldolgozás során azonban előfordulhat hiba, például a felhasználónév már foglalt. Ebben az esetben a hibát a `addError()` segítségével visszaadjuk az űrlapnak, és hagyjuk, hogy újra kirajzolódjon, hibaüzenettel:

```php
$form->addError('Sorry, username is already in use.');
```

Az űrlap feldolgozása után átirányítjuk a következő oldalra. Ez megakadályozza, hogy az űrlapot véletlenül újra elküldjék a *frissítés*, *vissza* gombra kattintva, vagy a böngésző előzményeit mozgatva.

Alapértelmezés szerint az űrlapot POST módszerrel küldjük el ugyanarra az oldalra. Mindkettő megváltoztatható:

```php
$form->setAction('/submit.php');
$form->setMethod('GET');
```

És ez minden :-) Van egy működőképes és tökéletesen [biztosított |#Vulnerability Protection] űrlapunk.

Próbáljon meg több [űrlapvezérlőt |controls] hozzáadni.


Hozzáférés a vezérlőkhöz .[#toc-access-to-controls]
===================================================

Az űrlapot és az egyes vezérlőelemeket komponenseknek nevezzük. Ezek egy komponensfát hoznak létre, amelynek gyökere az űrlap. Az egyes vezérlőelemeket a következőképpen érheti el:

```php
$input = $form->getComponent('name');
// alternatív szintaxis: $input = $form['name'];

$button = $form->getComponent('send');
// alternatív szintaxis: $button = $form['send'];
```

A vezérlőelemek eltávolítása az unset használatával történik:

```php
unset($form['name']);
```


Érvényesítési szabályok .[#toc-validation-rules]
================================================

Itt az *érvényes* szót használták, de az űrlapnak még nincsenek érvényesítési szabályai. Javítsuk ki.

A név kötelező lesz, ezért jelöljük meg a `setRequired()` metódussal, amelynek argumentuma a hibaüzenet szövege, amely akkor jelenik meg, ha a felhasználó nem tölti ki. Ha nem adunk meg argumentumot, akkor az alapértelmezett hibaüzenetet használjuk.

```php
$form->addText('name', 'Name:')
	->setRequired('Please enter a name.');
```

Próbáljuk meg elküldeni az űrlapot a név kitöltése nélkül, és látni fogjuk, hogy hibaüzenet jelenik meg, és a böngésző vagy a szerver elutasítja a kitöltésig.

Ugyanakkor nem fogja tudni becsapni a rendszert azzal, hogy például csak szóközöket ír be a beviteli mezőbe. Szó sem lehet róla. A Nette automatikusan levágja a bal és jobb oldali szóközöket. Próbálja ki! Ezt mindig meg kellene tennie minden egysoros bevitelnél, de gyakran elfelejtik. A Nette automatikusan elvégzi. (Megpróbálhatja becsapni az űrlapokat, és többsoros karakterláncot küldhet névként. A Nette még ebben az esetben sem fog becsapni, és a sortörések szóközökre változnak).

Az űrlap mindig a szerveroldalon validálódik, de a JavaScript validáció is generálódik, ami gyors, és a felhasználó azonnal értesül a hibáról, anélkül, hogy az űrlapot a szerverre kellene küldeni. Ezt a `netteForms.js` szkript kezeli.
Adja hozzá az oldalhoz:

```latte
<script src="https://unpkg.com/nette-forms@3"></script>
```

Ha megnézi az űrlapot tartalmazó oldal forráskódját, észreveheti, hogy a Nette a szükséges mezőket a `required` CSS osztályú elemekbe illeszti be. Próbálja meg hozzáadni a következő stílust a sablonhoz, és a "Név" felirat piros lesz. Elegánsan jelöljük a kötelező mezőket a felhasználók számára:

```latte
<style>
.required label { color: maroon }
</style>
```

További érvényesítési szabályokat a `addRule()` módszerrel adunk hozzá. Az első paraméter a szabály, a második ismét a hibaüzenet szövege, és az opcionális érvényesítési szabály argumentum következhet. Mit jelent ez?

Az űrlap kap egy másik opcionális bemenetet *életkor* azzal a feltétellel, hogy annak számnak kell lennie (`addInteger()`) és bizonyos határok között (`$form::Range`). És itt fogjuk használni a `addRule()` harmadik argumentumát , magát a tartományt:

```php
$form->addInteger('age', 'Age:')
	->addRule($form::Range, 'You must be older 18 years and be under 120.', [18, 120]);
```

.[tip]
Ha a felhasználó nem tölti ki a mezőt, akkor az érvényesítési szabályok nem lesznek ellenőrizve, mivel a mező opcionális.

Nyilvánvalóan van hely egy kis refaktorálásra. A hibaüzenetben és a harmadik paraméterben a számok duplikáltan szerepelnek, ami nem ideális. Ha [többnyelvű űrlapot |rendering#translating] hoznánk létre, és a számokat tartalmazó üzenetet több nyelvre kellene lefordítani, ez megnehezítené az értékek módosítását. Emiatt a `%d` helyettesítő karakterek használhatók:

```php
	->addRule($form::Range, 'You must be older %d years and be under %d.', [18, 120]);
```

Térjünk vissza a *jelszó* mezőhöz, tegyük *követelményessé*, és ellenőrizzük a minimális jelszóhosszúságot (`$form::MinLength`), ismét az üzenetben szereplő helyettesítő karakterek segítségével:

```php
$form->addPassword('password', 'Password:')
	->setRequired('Pick a password')
	->addRule($form::MinLength, 'Your password has to be at least %d long', 8);
```

Adjunk hozzá egy `passwordVerify` mezőt az űrlaphoz, ahol a felhasználó újra beírja a jelszót, az ellenőrzéshez. Érvényesítési szabályok segítségével ellenőrizzük, hogy mindkét jelszó azonos-e (`$form::Equal`). Érvként pedig szögletes [zárójelek |#Access to Controls] segítségével megadjuk az első jelszóra való hivatkozást:

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

A `setOmitted()` segítségével egy olyan elemet jelöltünk meg, amelynek értéke nem igazán érdekel minket, és amely csak az érvényesítés miatt létezik. Az értékét nem adjuk át a `$data`.

Egy teljesen működőképes űrlapunk van, PHP és JavaScript validációval. A Nette validálási lehetőségei sokkal szélesebb körűek, létrehozhatunk feltételeket, megjeleníthetjük és elrejthetjük az oldal egyes részeit ezek alapján, stb. Mindent megtudhat az [űrlapok validálásáról |validation] szóló fejezetben.


Alapértelmezett értékek .[#toc-default-values]
==============================================

Gyakran állítunk be alapértelmezett értékeket űrlapvezérlőkhöz:

```php
$form->addEmail('email', 'Email')
	->setDefaultValue($lastUsedEmail);
```

Gyakran hasznos, ha egyszerre állítjuk be az összes vezérlőelem alapértelmezett értékeit. Például amikor az űrlapot rekordok szerkesztésére használjuk. Beolvassuk a rekordot az adatbázisból, és beállítjuk az alapértelmezett értékeket:

```php
//$row = ['name' => 'John', 'age' => '33', /* ... */];
$form->setDefaults($row);
```

A vezérlőelemek definiálása után hívjuk meg a `setDefaults()` címet.


Az űrlap megjelenítése .[#toc-rendering-the-form]
=================================================

Az űrlap alapértelmezés szerint táblázatként jelenik meg. Az egyes vezérlőelemek az alapvető webes hozzáférhetőségi irányelveket követik. Minden címke `<label>` elemként jön létre, és a bemenetükhöz kapcsolódik, a címkére kattintva a kurzor a bemenetre kerül.

Az egyes elemekhez bármilyen HTML-attribútumot beállíthatunk. Például adjunk hozzá egy helyőrzőt:

```php
$form->addInteger('age', 'Age:')
	->setHtmlAttribute('placeholder', 'Please fill in the age');
```

Valóban sokféleképpen lehet megjeleníteni egy űrlapot, ezért ez egy külön [fejezet a megjelenítésről |rendering].


Osztályok leképezése .[#toc-mapping-to-classes]
===============================================

Térjünk vissza az űrlapadatok feldolgozásához. A `getValues()` metódus a `ArrayHash` objektumként adta vissza a beküldött adatokat. Mivel ez egy általános osztály, valami olyasmi, mint a `stdClass`, hiányozni fog néhány kényelmi funkció a vele való munka során, például a tulajdonságok kódkiegészítése a szerkesztőkben vagy a statikus kódelemzésben. Ezt úgy lehetne megoldani, ha minden űrlaphoz külön osztály lenne, amelynek tulajdonságai az egyes vezérlőelemeket képviselik. Pl:

```php
class RegistrationFormData
{
	public string $name;
	public int $age;
	public string $password;
}
```

Alternatívaként használhatja a konstruktort is:

```php
class RegistrationFormData
{
	public function __construct(
		public string $name,
		public int $age,
		public string $password,
	) {
	}
}
```

Az adatosztály tulajdonságai lehetnek enumok is, és automatikusan le lesznek képezve. .{data-version:3.2.4}

Hogyan mondjuk meg a Nette-nek, hogy az adatokat ennek az osztálynak az objektumaként adja vissza nekünk? Egyszerűbb, mint gondolnád. Mindössze annyit kell tennünk, hogy paraméterként megadjuk a hidratálandó osztály nevét vagy objektumát:

```php
$data = $form->getValues(RegistrationFormData::class);
$name = $data->name;
```

A `'array'` is megadható paraméterként, és akkor az adatok tömbként térnek vissza.

Ha az űrlapok konténerekből álló többszintű struktúrából állnak, hozzon létre mindegyikhez külön osztályt:

```php
$form = new Form;
$person = $form->addContainer('person');
$person->addText('firstName');
/* ... */

class PersonFormData
{
	public string $firstName;
	public string $lastName;
}

class RegistrationFormData
{
	public PersonFormData $person;
	public int $age;
	public string $password;
}
```

A leképezés ekkor a `$person` tulajdonságtípusból tudja, hogy a konténert a `PersonFormData` osztályhoz kell leképeznie. Ha a tulajdonság tárolók tömbjét tartalmazná, adja meg a `array` típust, és adja át a leképezendő osztályt közvetlenül a tárolóhoz:

```php
$person->setMappedType(PersonFormData::class);
```

Egy űrlap adatosztályának javaslatát a `Nette\Forms\Blueprint::dataClass($form)` metódussal generálhatja, amely a böngészőoldalra nyomtatja ki. Ezután egyszerűen rákattintva kiválaszthatja és bemásolhatja a kódot a projektjébe. .{data-version:3.1.15}


Többszörös beküldőgombok .[#toc-multiple-submit-buttons]
========================================================

Ha az űrlapon egynél több gomb van, általában meg kell különböztetnünk, hogy melyiket nyomta meg. A gomb `isSubmittedBy()` metódusa adja vissza nekünk ezt az információt:

```php
$form->addSubmit('save', 'Mentés');
$form->addSubmit('delete', 'Törlés');

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

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

Ne hagyjuk ki a `$form->isSuccess()`, hogy ellenőrizzük az adatok érvényességét.

Ha egy űrlapot az <kbd>Enter</kbd> billentyűvel küldünk be, azt úgy kezeljük, mintha az első gombbal küldtük volna be.


Sebezhetőségi védelem .[#toc-vulnerability-protection]
======================================================

A Nette Framework nagy erőfeszítéseket tesz a biztonság érdekében, és mivel az űrlapok a leggyakoribb felhasználói bevitel, a Nette űrlapok szinte áthatolhatatlanok.

Amellett, hogy védi az űrlapokat az olyan jól ismert sebezhetőségek támadása ellen, mint a [Cross-Site Scripting (XSS |nette:glossary#cross-site-scripting-xss] ) és a [Cross-Site Request Forgery (CSRF |nette:glossary#cross-site-request-forgery-csrf] ), sok apró biztonsági feladatot is elvégez, amelyekre már nem kell gondolnia.

Például kiszűri az összes vezérlő karaktert a bemenetekből, és ellenőrzi az UTF-8 kódolás érvényességét, így az űrlapból származó adatok mindig tiszták lesznek. A kiválasztó dobozok és rádiólisták esetében ellenőrzi, hogy a kiválasztott elemek valóban a felkínáltak közül kerültek-e ki, és nem történt-e hamisítás. Már említettük, hogy az egysoros szövegbevitel esetében eltávolítja a sor végi karaktereket, amelyeket egy támadó oda küldhet. Többsoros bevitel esetén normalizálja a sor végi karaktereket. És így tovább.

A Nette olyan biztonsági réseket is kijavít az Ön számára, amelyekről a legtöbb programozónak fogalma sincs, hogy léteznek.

Az említett CSRF-támadás lényege, hogy a támadó egy olyan oldal meglátogatására csábítja az áldozatot, amely némán végrehajt egy kérést az áldozat böngészőjében a szerver felé, ahová az áldozat éppen be van jelentkezve, és a szerver azt hiszi, hogy a kérést az áldozat akaratából tette. Ezért a Nette megakadályozza, hogy az űrlapot egy másik tartományból POST-on keresztül küldjék el. Ha valamilyen oknál fogva ki akarja kapcsolni a védelmet, és engedélyezni szeretné, hogy az űrlapot egy másik tartományból küldjék el, használja a következőt:

```php
$form->allowCrossOrigin(); // FIGYELEM! Kikapcsolja a védelmet!
```

Ez a védelem a `_nss` nevű SameSite cookie-t használja. Ezért hozzon létre egy űrlapot az első kimenet kiürítése előtt, hogy a cookie-t el lehessen küldeni.

A SameSite cookie-védelem nem biztos, hogy 100%-ig megbízható, ezért érdemes bekapcsolni a token-védelmet:

```php
$form->addProtection();
```

Erősen ajánlott ezt a védelmet alkalmazni az alkalmazás adminisztrációs részében lévő, érzékeny adatokat módosító űrlapokra. A keretrendszer a CSRF-támadás ellen a munkamenetben tárolt hitelesítési token generálásával és érvényesítésével védekezik (az érv a token lejárta esetén megjelenő hibaüzenet). Ezért szükséges, hogy az űrlap megjelenítése előtt elinduljon egy munkamenet. A webhely adminisztrációs részében a munkamenet általában már elindult, a felhasználó bejelentkezése miatt.
Ellenkező esetben a munkamenetet a `Nette\Http\Session::start()` metódussal kell elindítani.

Tehát van egy gyors bevezetésünk a Nette űrlapokba. További inspirációért próbálja megkeresni a disztribúcióban található [példák |https://github.com/nette/forms/tree/master/examples] könyvtárát.