Obrazci, ki se uporabljajo samostojno
*************************************

.[perex]
Nette Forms bistveno olajša ustvarjanje in obdelavo spletnih obrazcev. V svojih aplikacijah jih lahko uporabljate povsem samostojno, brez preostalega ogrodja, kar bomo prikazali v tem poglavju.

Če pa uporabljate aplikacijo Nette in predstavnike, je za vas na voljo priročnik: [Obrazci v predstavnikih |in-presenter].


Prvi obrazec .[#toc-first-form]
===============================

Poskusili bomo napisati preprost obrazec za registracijo. Njegova koda bo videti takole ("celotna koda":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');
```

Izpišimo ga:

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

in rezultat naj bo videti takole:

[* form-en.webp *]

Obrazec je objekt razreda `Nette\Forms\Form` (razred `Nette\Application\UI\Form` se uporablja v predstavitvah). Dodali smo mu kontrolne elemente ime, geslo in gumb za pošiljanje.

Zdaj bomo obrazec oživili. Z vprašanjem `$form->isSuccess()` bomo ugotovili, ali je bil obrazec poslan in ali je bil pravilno izpolnjen. Če je odgovor pritrdilen, bomo podatke izpisali. Za definicijo obrazca bomo dodali:

```php
if ($form->isSuccess()) {
	echo 'The form has been filled in and submitted correctly';
	$data = $form->getValues();
	// $data->name vsebuje ime
	// $data->password vsebuje geslo
	var_dump($data);
}
```

Metoda `getValues()` vrne poslane podatke v obliki objekta [ArrayHash |utils:arrays#ArrayHash]. Kako to spremeniti, bomo pokazali [pozneje |#Mapping to Classes]. Spremenljivka `$data` vsebuje ključa `name` in `password` s podatki, ki jih je vnesel uporabnik.

Običajno podatke pošljemo neposredno v nadaljnjo obdelavo, ki je lahko na primer vstavljanje v podatkovno zbirko. Vendar pa lahko med obdelavo pride do napake, na primer uporabniško ime je že zasedeno. V tem primeru napako posredujemo nazaj v obrazec s pomočjo `addError()` in ga pustimo ponovno narisati, s sporočilom o napaki:

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

Po obdelavi obrazca bomo preusmerili na naslednjo stran. S tem preprečimo, da bi obrazec nenamerno ponovno poslali s klikom na gumb *osvežitev*, *povratek* ali s premikanjem zgodovine brskalnika.

Privzeto se obrazec pošlje z metodo POST na isto stran. Oboje lahko spremenite:

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

To je vse :-) Imamo funkcionalen in popolnoma [zavarovan |#Vulnerability Protection] obrazec.

Poskusite dodati več [kontrolnih elementov obrazca |controls].


Dostop do kontrolnih elementov .[#toc-access-to-controls]
=========================================================

Obrazec in njegove posamezne kontrole se imenujejo komponente. Ustvarjajo drevo komponent, katerega koren je obrazec. Do posameznih kontrolnih elementov lahko dostopate na naslednji način:

```php
$input = $form->getComponent('name');
// alternativna sintaksa: $input = $form['name'];

$button = $form->getComponent('send');
// alternativna sintaksa: $button = $form['send'];
```

Kontrolne elemente odstranite z uporabo funkcije unset:

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


Pravila potrjevanja .[#toc-validation-rules]
============================================

Tu je bila uporabljena beseda *valid*, vendar obrazec še nima pravil potrjevanja. To popravimo.

Ime bo obvezno, zato ga bomo označili z metodo `setRequired()`, katere argument je besedilo sporočila o napaki, ki se prikaže, če ga uporabnik ne izpolni. Če argument ni naveden, se uporabi privzeto sporočilo o napaki.

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

Poskusite oddati obrazec brez izpolnjenega imena in videli boste, da se bo prikazalo sporočilo o napaki, brskalnik ali strežnik pa ga bo zavrnil, dokler ga ne izpolnite.

Hkrati sistema ne boste mogli prevarati tako, da boste v vnos vnesli samo presledke, na primer. Na noben način. Nette samodejno obreže leve in desne bele prostore. Preizkusite. To je nekaj, kar bi morali vedno narediti pri vsakem enovrstičnem vnosu, vendar se na to pogosto pozablja. Nette to stori samodejno. (Lahko poskusite prevarati obrazce in kot ime pošljete večvrstični niz. Tudi v tem primeru se Nette ne bo pustil preslepiti in prelomi vrstic se bodo spremenili v presledke.)

Obrazec se vedno potrdi na strani strežnika, vendar se ustvari tudi potrditev JavaScript, ki je hitra in uporabnik takoj izve za napako, ne da bi mu bilo treba obrazec poslati v strežnik. Za to poskrbi skripta `netteForms.js`.
Dodajte jo na stran:

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

Če pogledate izvorno kodo strani z obrazcem, lahko opazite, da Nette vstavi zahtevana polja v elemente z razredom CSS `required`. Poskusite v predlogo dodati naslednji slog in oznaka "Ime" bo rdeča. Na eleganten način označimo zahtevana polja za uporabnike:

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

Dodatna pravila potrjevanja bomo dodali z metodo `addRule()`. Prvi parameter je pravilo, drugi je spet besedilo sporočila o napaki, sledi pa lahko neobvezni argument pravila potrjevanja. Kaj to pomeni?

Obrazec bo dobil še en izbirni vnos *starost* s pogojem, da mora biti številka (`addInteger()`) in v določenih mejah (`$form::Range`). In tu bomo uporabili tretji argument `addRule()`, tj. samo območje:

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

.[tip]
Če uporabnik polja ne izpolni, se pravila potrjevanja ne bodo preverila, saj je polje neobvezno.

Očitno je na voljo prostor za majhno preoblikovanje. V sporočilu o napaki in v tretjem parametru so številke navedene podvojeno, kar ni idealno. Če bi ustvarjali [večjezični obrazec |rendering#translating] in bi bilo treba sporočilo s številkami prevesti v več jezikov, bi bilo spreminjanje vrednosti težje. Zato lahko uporabimo nadomestne znake `%d`:

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

Vrnimo se k polju *geslo*, naredimo ga *zahtevno* in preverimo najmanjšo dolžino gesla (`$form::MinLength`), pri čemer ponovno uporabimo nadomestne znake v sporočilu:

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

Za preverjanje bomo obrazcu dodali polje `passwordVerify`, kamor uporabnik ponovno vnese geslo. Z uporabo pravil potrjevanja preverimo, ali sta obe gesli enaki (`$form::Equal`). Kot argument pa podamo sklic na prvo geslo z uporabo oglatih [oklepajev |#Access to Controls]:

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

Z uporabo `setOmitted()` smo označili element, katerega vrednost nas v resnici ne zanima in ki obstaja le za potrjevanje. Njegove vrednosti ne posredujemo v `$data`.

Imamo popolnoma funkcionalen obrazec s preverjanjem v PHP in JavaScript. Nettejeve zmožnosti potrjevanja so veliko širše, saj lahko ustvarite pogoje, v skladu z njimi prikažete in skrijete dele strani itd. Vse boste izvedeli v poglavju o [potrjevanju obrazca |validation].


Privzete vrednosti .[#toc-default-values]
=========================================

Pogosto nastavljamo privzete vrednosti za kontrolne elemente obrazca:

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

Pogosto je koristno nastaviti privzete vrednosti za vse kontrole naenkrat. Na primer, ko se obrazec uporablja za urejanje zapisov. Zapise preberemo iz podatkovne zbirke in jih nastavimo kot privzete vrednosti:

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

Po definiranju kontrolnih elementov pokličemo `setDefaults()`.


Prikazovanje obrazca .[#toc-rendering-the-form]
===============================================

Obrazec je privzeto prikazan kot tabela. Posamezni kontrolni elementi upoštevajo osnovne smernice spletne dostopnosti. Vse oznake so ustvarjene kot `<label>` elementi in so povezani z njihovimi vhodi, klik na etiketo pa premakne kazalec na vhod.

Za vsak element lahko nastavimo poljubne atribute HTML. Dodajte na primer nadomestno mesto:

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

V tem poglavju je veliko načinov upodabljanja obrazca, zato je namenjeno prav [upodabljanju |rendering].


Prikazovanje v razrede .[#toc-mapping-to-classes]
=================================================

Vrnimo se k obdelavi podatkov iz obrazca. Metoda `getValues()` je posredovane podatke vrnila kot predmet `ArrayHash`. Ker je to splošen razred, nekaj podobnega kot `stdClass`, bomo pri delu z njim prikrajšani za nekaj udobja, na primer za dopolnjevanje kode za lastnosti v urejevalnikih ali statično analizo kode. To bi lahko rešili tako, da bi za vsak obrazec imeli poseben razred, katerega lastnosti bi predstavljale posamezne kontrole. Npr:

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

Od različice PHP 8.0 lahko uporabite eleganten zapis, ki uporablja konstruktor:

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

Kako reči Nettu, naj nam podatke vrne kot predmete tega razreda? Lažje, kot si mislite. Vse, kar morate storiti, je, da kot parameter navedete ime razreda ali objekta, ki ga želite hidrirati:

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

Kot parameter lahko navedete tudi `'array'`, nato pa se podatki vrnejo kot polje.

Če so obrazci sestavljeni iz večnivojske strukture, sestavljene iz vsebnikov, ustvarite ločen razred za vsakega od njih:

```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;
}
```

Prikazovanje nato na podlagi vrste lastnosti `$person` ugotovi, da mora vsebnik prikazati v razred `PersonFormData`. Če bi lastnost vsebovala polje vsebnikov, navedite tip `array` in razred, ki ga je treba preslikati neposredno na vsebnik:

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

Predlog podatkovnega razreda obrazca lahko ustvarite z metodo `Nette\Forms\Blueprint::dataClass($form)`, ki ga izpiše na strani brskalnika. Nato lahko preprosto kliknete, da izberete in kopirate kodo v svoj projekt. .{data-version:3.1.15}


Več gumbov za pošiljanje .[#toc-multiple-submit-buttons]
========================================================

Če ima obrazec več kot en gumb, moramo običajno razlikovati, kateri je bil pritisnjen. Metoda `isSubmittedBy()` gumba nam vrne to informacijo:

```php
$form->addSubmit('save', 'Save');
$form->addSubmit('delete', 'Delete');

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

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

Ne izpustite `$form->isSuccess()`, da preverite veljavnost podatkov.

Ko je obrazec oddan s tipko <kbd>Enter</kbd>, se obravnava, kot da bi bil oddan s prvo tipko.


Zaščita pred ranljivostmi .[#toc-vulnerability-protection]
==========================================================

Okvir Nette si zelo prizadeva biti varen, in ker so obrazci najpogostejši uporabniški vnos, so obrazci Nette tako dobro kot neprepustni.

Poleg zaščite obrazcev pred napadi dobro znanih ranljivosti, kot sta [Cross-Site Scripting (XSS |nette:glossary#cross-site-scripting-xss] ) in [Cross-Site Request Forgery (CSRF) |nette:glossary#cross-site-request-forgery-csrf], opravi veliko manjših varnostnih opravil, o katerih vam ni treba več razmišljati.

Na primer, iz vnosov filtrira vse kontrolne znake in preverja veljavnost kodiranja UTF-8, tako da bodo podatki iz obrazca vedno čisti. Pri izbirnih poljih in radijskih seznamih preveri, ali so bili izbrani elementi dejansko izmed ponujenih in ni prišlo do ponarejanja. Omenili smo že, da pri enovrstičnem vnosu besedila odstrani znake s konca vrstice, ki bi jih lahko tja poslal napadalec. Pri večvrstičnih vnosih normalizira znake na koncu vrstice. In tako naprej.

Nette za vas odpravi varnostne ranljivosti, za katere večina programerjev nima pojma, da obstajajo.

Pri omenjenem napadu CSRF gre za to, da napadalec žrtev zvabi k obisku strani, ki v brskalniku žrtve tiho izvrši zahtevo strežniku, v katerega je žrtev trenutno prijavljena, strežnik pa verjame, da je zahtevo po svoji volji izvršila žrtev. Zato Nette prepreči, da bi bil obrazec oddan prek protokola POST iz druge domene. Če iz nekega razloga želite izklopiti zaščito in dovoliti oddajo obrazca iz druge domene, uporabite:

```php
$form->allowCrossOrigin(); // POZOR! Izklopi zaščito!
```

Ta zaščita uporablja piškotek SameSite z imenom `_nss`. Zato ustvarite obrazec, preden izpraznite prvi izhod, da se lahko pošlje piškotek.

Zaščita piškotkov SameSite morda ni 100-odstotno zanesljiva, zato je dobro vklopiti zaščito s žetoni:

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

To zaščito je priporočljivo uporabiti za obrazce v upravnem delu aplikacije, ki spreminjajo občutljive podatke. Okvir ščiti pred napadom CSRF z generiranjem in potrjevanjem avtentikacijskega žetona, ki je shranjen v seji (argument je sporočilo o napaki, ki se prikaže, če je žeton potekel). Zato je treba pred prikazom obrazca zagnati sejo. V upravljalnem delu spletnega mesta je seja običajno že začeta zaradi prijave uporabnika.
V nasprotnem primeru sejo zaženite z metodo `Nette\Http\Session::start()`.

Tako smo na hitro spoznali obrazce v Nette. Za več navdiha poskusite poiskati v imeniku s [primeri |https://github.com/nette/forms/tree/master/examples] v distribuciji.