Sunuculardaki Formlar
*********************

.[perex]
Nette Forms, web formları oluşturmayı ve işlemeyi önemli ölçüde kolaylaştırır. Bu bölümde, formları sunumların içinde nasıl kullanacağınızı öğreneceksiniz.

Çerçevenin geri kalanı olmadan bunları tamamen bağımsız olarak kullanmakla ilgileniyorsanız, [bağımsız formlar |standalone] için bir kılavuz vardır.


İlk Form .[#toc-first-form]
===========================

Basit bir kayıt formu yazmaya çalışacağız. Kodu şu şekilde görünecektir:

```php
use Nette\Application\UI\Form;

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

ve tarayıcıda sonuç aşağıdaki gibi görünmelidir:

[* form-en.webp *]

Sunucudaki form `Nette\Application\UI\Form` sınıfının bir nesnesidir, selefi `Nette\Forms\Form` bağımsız kullanım için tasarlanmıştır. Biz buna isim, şifre ve gönderme butonu alanlarını ekledik. Son olarak, `$form->onSuccess` satırında form gönderildikten ve başarılı bir doğrulama yapıldıktan sonra `$this->formSucceeded()` metodunun çağrılması gerektiği yazıyor.

Sunucunun bakış açısından, form ortak bir bileşendir. Bu nedenle, bir bileşen olarak ele alınır ve [fabrika yöntemi |application:components#Factory Methods] kullanılarak sunucuya dahil edilir. Bu şekilde görünecektir:

```php .{file:app/UI/Home/HomePresenter.php}
use Nette;
use Nette\Application\UI\Form;

class HomePresenter extends Nette\Application\UI\Presenter
{
	protected function createComponentRegistrationForm(): Form
	{
		$form = new Form;
		$form->addText('name', 'Name:');
		$form->addPassword('password', 'Password:');
		$form->addSubmit('send', 'Sign up');
		$form->onSuccess[] = [$this, 'formSucceeded'];
		return $form;
	}

	public function formSucceeded(Form $form, $data): void
	{
		// burada form tarafından gönderilen verileri işleyeceğiz
		// $data->name isim içeriyor
		// $data->password parola içerir
		$this->flashMessage('Başarıyla kaydoldunuz.');
		$this->redirect('Home:');
	}
}
```

Ve şablonda render işlemi `{control}` etiketi kullanılarak yapılır:

```latte .{file:app/UI/Home/default.latte}
<h1>Registration</h1>

{control registrationForm}
```

Ve hepsi bu kadar :-) İşlevsel ve mükemmel şekilde [güvence |#Vulnerability Protection] altına alınmış bir formumuz var.

Şimdi muhtemelen bunun çok hızlı olduğunu düşünüyor, `formSucceeded()` yönteminin nasıl çağrıldığını ve aldığı parametrelerin ne olduğunu merak ediyorsunuz. Elbette haklısınız, bu bir açıklamayı hak ediyor.

Nette, [Hollywood tarzı |application:components#Hollywood style] olarak adlandırdığımız harika bir mekanizma ile geliyor. Sürekli olarak bir şey olup olmadığını sormak zorunda kalmak yerine ("form gönderildi mi?", "geçerli bir şekilde gönderildi mi?" veya "sahte değil mi?"), framework'e "form geçerli bir şekilde tamamlandığında, bu yöntemi çağır" diyorsunuz ve üzerinde daha fazla çalışmayı bırakıyorsunuz. JavaScript'te programlama yapıyorsanız, bu tarz programlamaya aşinasınızdır. Belirli bir [olay |nette:glossary#Events] gerçekleştiğinde çağrılan fonksiyonlar yazarsınız. Ve dil onlara uygun argümanları iletir.

Yukarıdaki sunum kodu bu şekilde oluşturulmuştur. `$form->onSuccess` dizisi, form gönderildiğinde ve doğru şekilde doldurulduğunda Nette'in çağıracağı PHP geri aramalarının listesini temsil eder.
Sunucunun [yaşam döngüsü |application:presenters#Life Cycle of Presenter] içinde bu bir sinyal olarak adlandırılır, bu nedenle `action*` yönteminden sonra ve `render*` yönteminden önce çağrılırlar.
Ve her geri aramaya ilk parametre olarak formun kendisini ve ikinci parametre olarak da [ArrayHash |utils:arrays#ArrayHash] nesnesi olarak gönderilen verileri aktarır. Form nesnesine ihtiyacınız yoksa ilk parametreyi atlayabilirsiniz. İkinci parametre daha da kullanışlı olabilir, ancak bunu daha [sonra |#Mapping to Classes] anlatacağız.

`$data` nesnesi, kullanıcı tarafından girilen verilerle birlikte `name` ve `password` özelliklerini içerir. Genellikle verileri, örneğin veritabanına ekleme gibi daha ileri işlemler için doğrudan göndeririz. Ancak, işleme sırasında bir hata oluşabilir, örneğin kullanıcı adı zaten alınmış olabilir. Bu durumda, `addError()` adresini kullanarak hatayı forma geri iletiriz ve bir hata mesajıyla birlikte yeniden çizilmesine izin veririz:

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

Buna ek olarak `onSuccess`, ayrıca `onSubmit`: form doğru doldurulmamış olsa bile form gönderildikten sonra geri aramalar her zaman çağrılır. Ve son olarak `onError`: geri aramalar yalnızca gönderim geçerli değilse çağrılır. Hatta `onSuccess` veya `onSubmit` adresindeki formu `addError()` adresini kullanarak geçersiz kılsak bile çağrılırlar.

Formu işledikten sonra bir sonraki sayfaya yönlendireceğiz. Bu, formun *yenile*, *geri* düğmesine tıklanarak veya tarayıcı geçmişi taşınarak istenmeden yeniden gönderilmesini önler.

Daha fazla [form denetimi |controls] eklemeyi deneyin.


Kontrollere Erişim .[#toc-access-to-controls]
=============================================

Form, sunucunun bir bileşenidir, bizim durumumuzda `registrationForm` olarak adlandırılmıştır (fabrika yönteminin adından sonra `createComponentRegistrationForm`), bu nedenle sunucunun herhangi bir yerinde formu kullanarak forma ulaşabilirsiniz:

```php
$form = $this->getComponent('registrationForm');
// alternatif sözdizimi: $form = $this['registrationForm'];
```

Ayrıca bireysel form kontrolleri de bileşenlerdir, bu nedenle onlara da aynı şekilde erişebilirsiniz:

```php
$input = $form->getComponent('name'); // veya $input = $form['name'];
$button = $form->getComponent('send'); // veya $button = $form['send'];
```

Kontroller unset kullanılarak kaldırılır:

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


Doğrulama Kuralları .[#toc-validation-rules]
============================================

Geçerli* kelimesi birkaç kez kullanıldı, ancak formun henüz doğrulama kuralları yok. Hadi düzeltelim.

Ad zorunlu olacaktır, bu nedenle onu, argümanı kullanıcı doldurmazsa görüntülenecek hata mesajının metni olan `setRequired()` yöntemiyle işaretleyeceğiz. Herhangi bir argüman verilmezse, varsayılan hata mesajı kullanılır.

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

İsim doldurulmadan formu göndermeye çalıştığınızda bir hata mesajının görüntülendiğini ve siz doldurana kadar tarayıcı veya sunucunun formu reddettiğini göreceksiniz.

Aynı zamanda, örneğin girişe sadece boşluk yazarak sistemi aldatamazsınız. Mümkün değil. Nette sol ve sağ boşlukları otomatik olarak keser. Bunu deneyin. Bu, her tek satırlık girişte her zaman yapmanız gereken bir şeydir, ancak genellikle unutulur. Nette bunu otomatik olarak yapar. (Formları kandırmayı deneyebilir ve isim olarak çok satırlı bir dize gönderebilirsiniz. Burada bile Nette aldanmayacak ve satır sonları boşluk olarak değişecektir).

Form her zaman sunucu tarafında doğrulanır, ancak JavaScript doğrulaması da oluşturulur, bu da hızlıdır ve kullanıcı formu sunucuya göndermek zorunda kalmadan hatayı hemen öğrenir. Bu işlem `netteForms.js` komut dosyası tarafından gerçekleştirilir.
Bunu düzen şablonuna ekleyin:

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

Formun bulunduğu sayfanın kaynak koduna bakarsanız, Nette'in gerekli alanları `required` CSS sınıfına sahip öğelere eklediğini fark edebilirsiniz. Aşağıdaki stili şablona eklemeyi deneyin, "Ad" etiketi kırmızı olacaktır. Kullanıcılar için gerekli alanları zarif bir şekilde işaretliyoruz:

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

Ek doğrulama kuralları `addRule()` yöntemi ile eklenecektir. İlk parametre kuraldır, ikincisi yine hata mesajının metnidir ve isteğe bağlı doğrulama kuralı argümanı takip edebilir. Bu ne anlama geliyor?

Form, bir sayı olması (`addInteger()`) ve belirli sınırlar içinde olması (`$form::Range`) koşuluyla başka bir isteğe bağlı girdi *yaş* alacaktır. Ve burada `addRule()`'un üçüncü argümanı olan aralığın kendisini kullanacağız:

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

.[tip]
Kullanıcı alanı doldurmazsa, alan isteğe bağlı olduğu için doğrulama kuralları doğrulanmayacaktır.

Açıkçası küçük bir yeniden düzenleme için yer mevcut. Hata mesajında ve üçüncü parametrede, sayılar çift olarak listelenmiştir ve bu ideal değildir. [Çok dilli |rendering#translating] bir [form |rendering#translating] oluşturuyor olsaydık ve sayıları içeren mesajın birden fazla dile çevrilmesi gerekseydi, değerleri değiştirmek daha zor olurdu. Bu nedenle, `%d` ikame karakterleri kullanılabilir:

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

Parola* alanına geri dönelim, bunu *gerekli* yapalım ve yine mesajdaki yedek karakterleri kullanarak minimum parola uzunluğunu (`$form::MinLength`) doğrulayalım:

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

Kontrol için kullanıcının şifreyi tekrar girdiği forma `passwordVerify` şeklinde bir alan ekleyeceğiz. Doğrulama kurallarını kullanarak, her iki şifrenin de aynı olup olmadığını kontrol ediyoruz (`$form::Equal`). Ve bir argüman olarak [köşeli |#Access to Controls] parantez kullanarak ilk şifreye bir referans veriyoruz:

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

`setOmitted()` adresini kullanarak, değerini gerçekten önemsemediğimiz ve yalnızca doğrulama için var olan bir öğeyi işaretledik. Değeri `$data` adresine aktarılmaz.

PHP ve JavaScript'te doğrulama ile tamamen işlevsel bir formumuz var. Nette'nin doğrulama yetenekleri çok daha geniştir, koşullar oluşturabilir, bunlara göre bir sayfanın bölümlerini görüntüleyebilir ve gizleyebilirsiniz, vb. Her şeyi [form doğrul |validation] ama bölümünde bulabilirsiniz.


Varsayılan Değerler .[#toc-default-values]
==========================================

Form denetimleri için genellikle varsayılan değerler ayarlarız:

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

Genellikle tüm kontroller için varsayılan değerleri aynı anda ayarlamak yararlıdır. Örneğin, form kayıtları düzenlemek için kullanıldığında. Kaydı veritabanından okuruz ve varsayılan değerler olarak ayarlarız:

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

Kontrolleri tanımladıktan sonra `setDefaults()` adresini çağırın.


Formun Oluşturulması .[#toc-rendering-the-form]
===============================================

Varsayılan olarak, form bir tablo olarak işlenir. Bireysel kontroller temel web erişilebilirlik yönergelerini takip eder. Tüm etiketler şu şekilde oluşturulur `<label>` elemanlarıdır ve girişleriyle ilişkilidir, etikete tıklamak imleci girişe taşır.

Her öğe için herhangi bir HTML niteliği ayarlayabiliriz. Örneğin, bir yer tutucu ekleyin:

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

Bir formu oluşturmanın gerçekten pek çok yolu vardır, bu yüzden bu [bölüm |rendering] oluşturma konusuna ayrılmıştır.


Sınıflarla Eşleme .[#toc-mapping-to-classes]
============================================

İkinci parametre olarak `$data` gönderilen veriyi bir `ArrayHash` nesnesi olarak alan `formSucceeded()` yöntemine geri dönelim. Bu `stdClass` gibi genel bir sınıf olduğundan, onunla çalışırken editörlerdeki özellikler için kod tamamlama veya statik kod analizi gibi bazı kolaylıklardan yoksun kalacağız. Bu, her form için, özellikleri ayrı kontrolleri temsil eden özel bir sınıfa sahip olarak çözülebilir. Örneğin:

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

PHP 8.0'dan itibaren, bir kurucu kullanan bu zarif gösterimi kullanabilirsiniz:

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

Nette'e verileri bu sınıfın nesneleri olarak döndürmesini nasıl söyleyebilirim? Düşündüğünüzden daha kolay. Tek yapmanız gereken, işleyicideki `$data` parametresinin türü olarak sınıfı belirtmektir:

```php
public function formSucceeded(Form $form, RegistrationFormData $data): void
{
	// $name is instance of RegistrationFormData
	$name = $data->name;
	// ...
}
```

Ayrıca tür olarak `array` belirtebilirsiniz ve ardından verileri bir dizi olarak iletir.

Benzer şekilde, parametre olarak hidrate edilecek bir sınıf adı veya nesne olarak ilettiğimiz `getValues()` yöntemini kullanabilirsiniz:

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

Formlar konteynerlerden oluşan çok seviyeli bir yapıdan oluşuyorsa, her biri için ayrı bir sınıf oluşturun:

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

Eşleme daha sonra `$person` özellik türünden konteyneri `PersonFormData` sınıfına eşlemesi gerektiğini bilir. Özellik bir kapsayıcı dizisi içerecekse, `array` türünü sağlayın ve doğrudan kapsayıcıyla eşlenecek sınıfı iletin:

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

Tarayıcı sayfasına yazdıracak olan `Nette\Forms\Blueprint::dataClass($form)` yöntemini kullanarak bir formun veri sınıfı için bir öneri oluşturabilirsiniz. Daha sonra kodu seçmek ve projenize kopyalamak için tıklamanız yeterlidir. .{data-version:3.1.15}


Çoklu Gönder Düğmeleri .[#toc-multiple-submit-buttons]
======================================================

Formda birden fazla düğme varsa, genellikle hangisine basıldığını ayırt etmemiz gerekir. Her düğme için kendi fonksiyonumuzu oluşturabiliriz. Bunu `onClick` [olayı |nette:glossary#Events] için bir işleyici olarak ayarlayın:

```php
$form->addSubmit('save', 'Save')
	->onClick[] = [$this, 'saveButtonPressed'];

$form->addSubmit('delete', 'Delete')
	->onClick[] = [$this, 'deleteButtonPressed'];
```

Bu işleyiciler de `onSuccess` olayında olduğu gibi yalnızca formun geçerli olması durumunda çağrılır. Aradaki fark, belirttiğiniz türe bağlı olarak ilk parametrenin form yerine gönder düğmesi nesnesi olabilmesidir:

```php
public function saveButtonPressed(Nette\Forms\Controls\Button $button, $data)
{
	$form = $button->getForm();
	// ...
}
```

Bir form <kbd>Enter</kbd> tuşu ile gönderildiğinde, ilk düğme ile gönderilmiş gibi işlem görür.


Olay onAnchor .[#toc-event-onanchor]
====================================

Bir fabrika yönteminde ( `createComponentRegistrationForm` gibi) bir form oluşturduğunuzda, henüz gönderilip gönderilmediğini veya hangi verilerle gönderildiğini bilmez. Ancak, gönderilen değerleri bilmemiz gereken durumlar vardır, belki de formun nasıl görüneceği onlara bağlıdır veya bağımlı seçim kutuları vb. için kullanılırlar.

Bu nedenle, formu oluşturan kodun, form bağlandığında çağrılmasını sağlayabilirsiniz, yani form zaten sunum yapan kişiye bağlıdır ve gönderilen verileri bilir. Böyle bir kodu `$onAnchor` dizisine koyacağız:

```php
$country = $form->addSelect('country', 'Country:', $this->model->getCountries());
$city = $form->addSelect('city', 'City:');

$form->onAnchor[] = function () use ($country, $city) {
	// form gönderildiği veriyi bildiğinde bu fonksiyon çağrılacaktır
	// böylece getValue() yöntemini kullanabilirsiniz
	$val = $country->getValue();
	$city->setItems($val ? $this->model->getCities($val) : []);
};
```


Güvenlik Açığı Koruması .[#toc-vulnerability-protection]
========================================================

Nette Framework güvenli olmak için büyük çaba sarf eder ve formlar en yaygın kullanıcı girdisi olduğundan, Nette formları aşılmaz kadar iyidir. Her şey dinamik ve şeffaf olarak korunur, hiçbir şeyin manuel olarak ayarlanması gerekmez.

Formları Siteler Arası Komut Dosyası [Yazma (XSS |nette:glossary#cross-site-scripting-xss] ) ve [Siteler Arası İstek Sahteciliği (CSRF) |nette:glossary#cross-site-request-forgery-csrf] gibi iyi bilinen güvenlik açıklarını hedef alan saldırılara karşı korumanın yanı sıra, artık düşünmek zorunda olmadığınız birçok küçük güvenlik görevini de yerine getirir.

Örneğin, girdilerden tüm kontrol karakterlerini filtreler ve UTF-8 kodlamasının geçerliliğini kontrol eder, böylece formdan gelen veriler her zaman temiz olur. Seçim kutuları ve radyo listeleri için, seçilen öğelerin gerçekten sunulanlardan olduğunu ve herhangi bir sahtecilik olmadığını doğrular. Tek satırlı metin girişi için, bir saldırganın oraya gönderebileceği satır sonu karakterlerini kaldırdığından daha önce bahsetmiştik. Çok satırlı girdiler için satır sonu karakterlerini normalleştirir. Ve böyle devam eder.

Nette, çoğu programcının varlığından bile haberdar olmadığı güvenlik açıklarını sizin için düzeltir.

Bahsedilen CSRF saldırısı, bir saldırganın kurbanı, kurbanın tarayıcısında kurbanın o anda oturum açtığı sunucuya sessizce bir istek yürüten bir sayfayı ziyaret etmesi için kandırması ve sunucunun, isteğin kurban tarafından isteğe bağlı olarak yapıldığına inanmasıdır. Bu nedenle Nette, formun başka bir etki alanından POST yoluyla gönderilmesini engeller. Herhangi bir nedenle korumayı kapatmak ve formun başka bir etki alanından gönderilmesine izin vermek istiyorsanız, şunu kullanın:

```php
$form->allowCrossOrigin(); // DİKKAT! Korumayı kapatır!
```

Bu koruma, `_nss` adlı bir SameSite çerezi kullanır. SameSite çerez koruması %100 güvenilir olmayabilir, bu nedenle token korumasını açmak iyi bir fikirdir:

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

Bu korumayı uygulamanızın hassas verileri değiştiren idari bölümündeki formlara uygulamanız şiddetle tavsiye edilir. Çerçeve, bir oturumda saklanan kimlik doğrulama belirtecini oluşturarak ve doğrulayarak CSRF saldırısına karşı koruma sağlar (argüman, belirtecin süresi dolmuşsa gösterilen hata mesajıdır). Bu nedenle formu görüntülemeden önce bir oturumun başlatılmış olması gerekir. Web sitesinin yönetim bölümünde, kullanıcının oturum açması nedeniyle oturum genellikle zaten başlatılmıştır.
Aksi takdirde, oturumu `Nette\Http\Session::start()` yöntemi ile başlatın.


Bir Formu Birden Fazla Sunucuda Kullanma .[#toc-using-one-form-in-multiple-presenters]
======================================================================================

Bir formu birden fazla sunucuda kullanmanız gerekiyorsa, bunun için daha sonra sunucuya aktaracağınız bir fabrika oluşturmanızı öneririz. Böyle bir sınıf için uygun bir konum, örneğin, `app/Forms` dizinidir.

Fabrika sınıfı şu şekilde görünebilir:

```php
use Nette\Application\UI\Form;

class SignInFormFactory
{
	public function create(): Form
	{
		$form = new Form;
		$form->addText('name', 'Name:');
		$form->addSubmit('send', 'Log in');
		return $form;
	}
}
```

Sunucu içerisindeki bileşenler için fabrika metodunda sınıfın formu üretmesini istiyoruz:

```php
public function __construct(
	private SignInFormFactory $formFactory,
) {
}

protected function createComponentSignInForm(): Form
{
	$form = $this->formFactory->create();
	// formu değiştirebiliriz, burada örneğin düğmenin üzerindeki etiketi değiştiriyoruz
	$form['login']->setCaption('Continue');
	$form->onSuccess[] = [$this, 'signInFormSubmitted']; // ve işleyici ekleyin
	return $form;
}
```

Form işleme işleyicisi fabrikadan da teslim edilebilir:

```php
use Nette\Application\UI\Form;

class SignInFormFactory
{
	public function create(): Form
	{
		$form = new Form;
		$form->addText('name', 'Name:');
		$form->addSubmit('send', 'Log in');
		$form->onSuccess[] = function (Form $form, $data): void {
			// gönderilen formumuzu burada işliyoruz
		};
		return $form;
	}
}
```

Böylece, Nette'deki formlara hızlı bir giriş yapmış olduk. Daha fazla ilham almak için dağıtımdaki [örnekler |https://github.com/nette/forms/tree/master/examples] dizinine bakmayı deneyin.