Form Elemanları

Standart form elemanlarının özeti.

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

Tek satırlık bir metin kutusu ekler (sınıf TextInput). Kullanıcı alanı doldurmazsa, boş bir dize '' döndürür veya setNullable() kullanarak null döndürmesini belirleyebilirsiniz.

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

UTF-8'i otomatik olarak doğrular, sol ve sağ boşlukları kırpar ve bir saldırganın gönderebileceği satır sonlarını kaldırır.

Maksimum uzunluk setMaxLength() ile sınırlandırılabilir. Kullanıcı tarafından girilen değeri değiştirmek addFilter() ile mümkündür.

setHtmlType() kullanarak metin kutusunun görsel karakterini search, tel veya url gibi türlere değiştirebilirsiniz, bkz. şartname. Tür değişikliğinin yalnızca görsel olduğunu ve doğrulama işlevinin yerini tutmadığını unutmayın. url türü için belirli bir URL kuralı eklemek uygundur.

number, range, email, date, datetime-local, time ve color gibi diğer giriş türleri için, sunucu tarafı doğrulaması sağlayan addInteger, addFloat, addEmail, addDate, addTime, addDateTime ve addColor gibi özel metotları kullanın. month ve week türleri henüz tüm tarayıcılarda tam olarak desteklenmemektedir.

Elemana, varsayılan değere benzeyen ancak kullanıcı değiştirmezse elemanın boş bir dize veya null döndürdüğü sözde boş değer (empty-value) atanabilir.

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

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

Çok satırlı metin girmek için bir alan ekler (sınıf TextArea). Kullanıcı alanı doldurmazsa, boş bir dize '' döndürür veya setNullable() kullanarak null döndürmesini belirleyebilirsiniz.

$form->addTextArea('note', 'Not:')
	->addRule($form::MaxLength, 'Not çok uzun', 10000);

UTF-8'i otomatik olarak doğrular ve satır ayırıcılarını \n olarak normalleştirir. Tek satırlık giriş alanının aksine, boşluk kırpma işlemi yapılmaz.

Maksimum uzunluk setMaxLength() ile sınırlandırılabilir. Kullanıcı tarafından girilen değeri değiştirmek addFilter() ile mümkündür. setEmptyValue() kullanarak sözde boş değer (empty-value) ayarlanabilir.

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

Tamsayı girmek için bir alan ekler (sınıf TextInput). Kullanıcı hiçbir şey girmezse tamsayı veya null döndürür.

$form->addInteger('year', 'Yıl:')
	->addRule($form::Range, 'Yıl %d ile %d arasında olmalıdır.', [1900, 2023]);

Eleman <input type="number"> olarak render edilir. setHtmlType() metodunu kullanarak türü, kaydırıcı şeklinde görüntülemek için range olarak veya number türünün özel davranışları olmayan standart bir metin alanı tercih ediyorsanız text olarak değiştirebilirsiniz.

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

Ondalık sayı girmek için bir alan ekler (sınıf TextInput). Kullanıcı hiçbir şey girmezse float veya null döndürür.

$form->addFloat('level', 'Seviye:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Seviye %d ile %d arasında olmalıdır.', [0, 100]);

Nette ve Chrome tarayıcısı, ondalık ayırıcı olarak hem virgülü hem de noktayı kabul eder. Bu işlevselliğin Firefox'ta da kullanılabilir olması için, ilgili eleman veya tüm sayfa için lang niteliğini ayarlamanız önerilir, örneğin <html lang="tr">.

addEmail (string|int $name, $label=null, int $maxLength=255): TextInput

E-posta adresi girmek için bir alan ekler (sınıf TextInput). Kullanıcı alanı doldurmazsa, boş bir dize '' döndürür veya setNullable() kullanarak null döndürmesini belirleyebilirsiniz.

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

Değerin geçerli bir e-posta adresi olup olmadığını doğrular. Alan adının gerçekten var olup olmadığı kontrol edilmez, yalnızca sözdizimi doğrulanır. UTF-8'i otomatik olarak doğrular, sol ve sağ boşlukları kırpar.

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

Şifre girmek için bir alan ekler (sınıf TextInput).

$form->addPassword('password', 'Şifre:')
	->setRequired()
	->addRule($form::MinLength, 'Şifre en az %d karakter olmalıdır', 8)
	->addRule($form::Pattern, 'Bir rakam içermelidir', '.*[0-9].*');

Form yeniden görüntülendiğinde alan boş olacaktır. UTF-8'i otomatik olarak doğrular, sol ve sağ boşlukları kırpar ve bir saldırganın gönderebileceği satır sonlarını kaldırır.

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

Bir onay kutusu ekler (sınıf Checkbox). İşaretli olup olmadığına bağlı olarak true veya false değerini döndürür.

$form->addCheckbox('agree', 'Şartları kabul ediyorum')
	->setRequired('Şartları kabul etmeniz gerekiyor');

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

Birden çok öğe seçmek için onay kutuları ekler (sınıf CheckboxList). Seçilen öğelerin anahtarlarından oluşan bir dizi döndürür. getSelectedItems() metodu anahtarlar yerine değerleri döndürür.

$form->addCheckboxList('colors', 'Renkler:', [
	'r' => 'kırmızı',
	'g' => 'yeşil',
	'b' => 'mavi',
]);

Sunulan öğelerin dizisini üçüncü parametre olarak veya setItems() metoduyla iletiriz.

setDisabled(['r', 'g']) kullanarak bireysel öğeleri devre dışı bırakabilirsiniz.

Eleman, sahtecilik yapılmadığını ve seçilen öğelerin gerçekten sunulanlardan biri olduğunu ve devre dışı bırakılmadığını otomatik olarak kontrol eder. getRawValue() metoduyla bu önemli kontrol olmadan gönderilen öğeleri alabilirsiniz.

Varsayılan seçili öğeleri ayarlarken, bunların sunulanlardan biri olup olmadığını da kontrol eder, aksi takdirde bir istisna fırlatır. Bu kontrol checkDefaultValue(false) ile kapatılabilir.

Formu GET metoduyla gönderiyorsanız, sorgu dizesinin boyutunu azaltan daha kompakt bir veri aktarım yöntemi seçebilirsiniz. Formun HTML niteliğini ayarlayarak etkinleştirilir:

$form->setHtmlAttribute('data-nette-compact');

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

Radyo düğmeleri ekler (sınıf RadioList). Seçilen öğenin anahtarını veya kullanıcı hiçbir şey seçmezse null döndürür. getSelectedItem() metodu anahtar yerine değeri döndürür.

$sex = [
	'm' => 'erkek',
	'f' => 'kadın',
];
$form->addRadioList('gender', 'Cinsiyet:', $sex);

Sunulan öğelerin dizisini üçüncü parametre olarak veya setItems() metoduyla iletiriz.

setDisabled(['m', 'f']) kullanarak bireysel öğeleri devre dışı bırakabilirsiniz.

Eleman, sahtecilik yapılmadığını ve seçilen öğenin gerçekten sunulanlardan biri olduğunu ve devre dışı bırakılmadığını otomatik olarak kontrol eder. getRawValue() metoduyla bu önemli kontrol olmadan gönderilen öğeyi alabilirsiniz.

Varsayılan seçili öğeyi ayarlarken, bunun sunulanlardan biri olup olmadığını da kontrol eder, aksi takdirde bir istisna fırlatır. Bu kontrol checkDefaultValue(false) ile kapatılabilir.

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

Bir seçme kutusu (select box) ekler (sınıf SelectBox). Seçilen öğenin anahtarını veya kullanıcı hiçbir şey seçmezse null döndürür. getSelectedItem() metodu anahtar yerine değeri döndürür.

$countries = [
	'TR' => 'Türkiye',
	'DE' => 'Almanya',
	'GB' => 'Büyük Britanya',
];

$form->addSelect('country', 'Ülke:', $countries)
	->setDefaultValue('TR');

Sunulan öğelerin dizisini üçüncü parametre olarak veya setItems() metoduyla iletiriz. Öğeler iki boyutlu bir dizi de olabilir:

$countries = [
	'Avrupa' => [
		'CZ' => 'Çek Cumhuriyeti',
		'DE' => 'Almanya',
		'FR' => 'Fransa',
	],
	'TR' => 'Türkiye',
	'US' => 'ABD',
	'?'  => 'diğer',
];

Seçme kutularında genellikle ilk öğenin özel bir anlamı vardır, bir eylem çağrısı olarak hizmet eder. Böyle bir öğe eklemek için setPrompt() metodu kullanılır.

$form->addSelect('country', 'Ülke:', $countries)
	->setPrompt('Ülke seçin');

setDisabled(['DE', 'FR']) kullanarak bireysel öğeleri devre dışı bırakabilirsiniz.

Varsayılan seçili öğeyi ayarlarken, bunun sunulanlardan biri olup olmadığını da kontrol eder, aksi takdirde bir istisna fırlatır. Bu kontrol checkDefaultValue(false) ile kapatılabilir.

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

Birden çok öğe seçmek için bir seçme kutusu ekler (sınıf MultiSelectBox). Seçilen öğelerin anahtarlarından oluşan bir dizi döndürür. getSelectedItems() metodu anahtarlar yerine değerleri döndürür.

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

Sunulan öğelerin dizisini üçüncü parametre olarak veya setItems() metoduyla iletiriz. Öğeler iki boyutlu bir dizi de olabilir.

setDisabled(['DE', 'GB']) kullanarak bireysel öğeleri devre dışı bırakabilirsiniz.

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

Dosya yüklemek için bir alan ekler (sınıf UploadControl). Kullanıcı hiçbir dosya göndermese bile bir FileUpload nesnesi döndürür, bu durum FileUpload::hasFile() metoduyla kontrol edilebilir.

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatar JPEG, PNG, GIF, WebP veya AVIF olmalıdır.')
	->addRule($form::MaxFileSize, 'Maksimum boyut 1 MB.', 1024 * 1024);

Dosya doğru şekilde yüklenemezse, form başarıyla gönderilmez ve bir hata görüntülenir. Yani, başarılı bir gönderimde FileUpload::isOk() metodunu doğrulamaya gerek yoktur.

FileUpload::getName() metodu tarafından döndürülen orijinal dosya adına asla güvenmeyin, istemci uygulamanıza zarar vermek veya hacklemek amacıyla kötü niyetli bir dosya adı göndermiş olabilir.

MimeType ve Image kuralları, istenen türü dosya imzasına göre algılar ve bütünlüğünü doğrulamaz. Bir resmin bozuk olup olmadığını, örneğin onu yükleme deneyerek öğrenebilirsiniz.

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

Aynı anda birden çok dosya yüklemek için bir alan ekler (sınıf UploadControl). FileUpload nesnelerinden oluşan bir dizi döndürür. Her birinde FileUpload::hasFile() metodu true döndürür.

$form->addMultiUpload('files', 'Dosyalar:')
	->addRule($form::MaxLength, 'En fazla %d dosya yüklenebilir', 10);

Dosyalardan herhangi biri doğru şekilde yüklenemezse, form başarıyla gönderilmez ve bir hata görüntülenir. Yani, başarılı bir gönderimde FileUpload::isOk() metodunu doğrulamaya gerek yoktur.

FileUpload::getName() metodu tarafından döndürülen orijinal dosya adlarına asla güvenmeyin, istemci uygulamanıza zarar vermek veya hacklemek amacıyla kötü niyetli bir dosya adı göndermiş olabilir.

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

Kullanıcının yıl, ay ve günden oluşan bir tarihi kolayca girmesini sağlayan bir alan ekler (sınıf DateTimeControl).

Varsayılan değer olarak DateTimeInterface arayüzünü uygulayan nesneleri, zaman içeren bir dizeyi veya UNIX zaman damgasını temsil eden bir sayıyı kabul eder. Aynı durum, izin verilen minimum ve maksimum tarihi tanımlayan Min, Max veya Range kurallarının argümanları için de geçerlidir.

$form->addDate('date', 'Tarih:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'Tarih en az bir ay önce olmalıdır.', new DateTime('-1 month'));

Standart olarak DateTimeImmutable nesnesi döndürür, setFormat() metoduyla metin biçimi veya zaman damgası belirtebilirsiniz:

$form->addDate('date', 'Tarih:')
	->setFormat('Y-m-d');

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

Kullanıcının saat, dakika ve isteğe bağlı olarak saniyeden oluşan bir zamanı kolayca girmesini sağlayan bir alan ekler (sınıf DateTimeControl).

Varsayılan değer olarak DateTimeInterface arayüzünü uygulayan nesneleri, zaman içeren bir dizeyi veya UNIX zaman damgasını temsil eden bir sayıyı kabul eder. Bu girdilerden yalnızca zaman bilgisi kullanılır, tarih göz ardı edilir. Aynı durum, izin verilen minimum ve maksimum zamanı tanımlayan Min, Max veya Range kurallarının argümanları için de geçerlidir. Ayarlanan minimum değer maksimum değerden yüksekse, gece yarısını aşan bir zaman aralığı oluşturulur.

$form->addTime('time', 'Saat:', withSeconds: true)
	->addRule($form::Range, 'Saat %d ile %d arasında olmalıdır.', ['12:30', '13:30']);

Standart olarak DateTimeImmutable nesnesi (1 Ocak yıl 1 tarihiyle) döndürür, setFormat() metoduyla metin biçimi belirtebilirsiniz:

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

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

Kullanıcının yıl, ay, gün, saat, dakika ve isteğe bağlı olarak saniyeden oluşan bir tarih ve saati kolayca girmesini sağlayan bir alan ekler (sınıf DateTimeControl).

$form->addDateTime('datetime', 'Tarih ve Saat:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'Tarih en az bir ay önce olmalıdır.', new DateTime('-1 month'));

Standart olarak DateTimeImmutable nesnesi döndürür, setFormat() metoduyla metin biçimi veya zaman damgası belirtebilirsiniz:

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

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

Renk seçmek için bir alan ekler (sınıf ColorPicker). Renk #rrggbb biçiminde bir dizedir. Kullanıcı seçim yapmazsa, siyah renk #000000 döndürülür.

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

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

Gizli bir alan ekler (sınıf HiddenField).

$form->addHidden('userid');

setNullable() kullanarak boş dize yerine null döndürmesini ayarlayabilirsiniz. Gönderilen değeri değiştirmek addFilter() ile mümkündür.

Eleman gizli olsa da, değerin hala bir saldırgan tarafından değiştirilebileceğini veya sahtesinin yapılabileceğini unutmamak önemlidir. Veri manipülasyonuyla ilgili güvenlik risklerini önlemek için sunucu tarafında alınan tüm değerleri her zaman dikkatlice doğrulayın ve geçerleyin.

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

Bir gönderme düğmesi ekler (sınıf SubmitButton).

$form->addSubmit('submit', 'Gönder');

Formda birden fazla gönderme düğmesi olabilir:

$form->addSubmit('register', 'Kaydol');
$form->addSubmit('cancel', 'İptal');

Hangisine tıklandığını öğrenmek için şunu kullanın:

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

Düğmeye basıldığında tüm formu doğrulamak istemiyorsanız (örneğin İptal veya Önizleme düğmeleri için), setValidationScope() kullanın.

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

Gönderme işlevi olmayan bir düğme ekler (sınıf Button). Bu nedenle, başka bir işlev için kullanılabilir, örneğin tıklandığında bir JavaScript fonksiyonunu çağırmak için.

$form->addButton('raise', 'Maaşı Artır')
	->setHtmlAttribute('onclick', 'raiseSalary()');

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

Resim şeklinde bir gönderme düğmesi ekler (sınıf ImageButton).

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

Birden fazla gönderme düğmesi kullanırken, hangisine tıklandığını $form['submit']->isSubmittedBy() kullanarak öğrenebilirsiniz.

addContainer (string|int $name): Container

Forma bir alt form (sınıf Container), yani bir konteyner ekler, buna forma eklediğimiz gibi diğer elemanları ekleyebiliriz. setDefaults() veya getValues() metotları da çalışır.

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Adınız:');
$sub1->addEmail('email', 'E-posta:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Adınız:');
$sub2->addEmail('email', 'E-posta:');

Gönderilen verileri daha sonra çok boyutlu bir yapı olarak döndürür:

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

Ayarların Özeti

Tüm elemanlarda aşağıdaki metotları çağırabiliriz (API dokümantasyonu içinde tam liste):

`setDefaultValue($value)`	varsayılan değeri ayarlar
`getValue()`	geçerli değeri alır
`setOmitted()`	Değerin Atlanması
`setDisabled()`	Elemanların Devre Dışı Bırakılması

Renderleme:

`setCaption($caption)`	eleman etiketini değiştirir
`setTranslator($translator)`	çevirmeni ayarlar
`setHtmlAttribute($name, $value)`	elementin HTML niteliğini ayarlar
`setHtmlId($id)`	HTML `id` niteliğini ayarlar
`setHtmlType($type)`	HTML `type` niteliğini ayarlar
`setHtmlName($name)`	HTML `name` niteliğini ayarlar
`setOption($key, $value)`	renderleme ayarları

Doğrulama:

`setRequired()`	zorunlu eleman
`addRule()`	doğrulama kuralı ayarı
`addCondition()`, `addConditionOn()`	doğrulama koşulunu ayarlar
`addError($message)`	hata mesajı iletme

addText(), addPassword(), addTextArea(), addEmail(), addInteger() elemanlarında aşağıdaki metotları çağırabiliriz:

`setNullable()`	getValue()'nin boş dize yerine `null` döndürüp döndürmeyeceğini ayarlar
`setEmptyValue($value)`	boş dize olarak kabul edilen özel bir değer ayarlar
`setMaxLength($length)`	izin verilen maksimum karakter sayısını ayarlar
`addFilter($filter)`	giriş düzenleme

Değerin Atlanması

Kullanıcı tarafından doldurulan değerle ilgilenmiyorsak, setOmitted() kullanarak onu $form->getValues() metodunun sonucundan veya işleyicilere iletilen verilerden çıkarabiliriz. Bu, çeşitli kontrol şifreleri, antispam elemanları vb. için kullanışlıdır.

$form->addPassword('passwordVerify', 'Kontrol için şifre:')
	->setRequired('Lütfen kontrol için şifreyi tekrar girin')
	->addRule($form::Equal, 'Şifreler eşleşmiyor', $form['password'])
	->setOmitted();

Elemanların Devre Dışı Bırakılması

Elemanlar setDisabled() ile devre dışı bırakılabilir. Böyle bir eleman kullanıcı tarafından düzenlenemez.

$form->addText('username', 'Kullanıcı adı:')
	->setDisabled();

Devre dışı bırakılmış elemanlar tarayıcı tarafından sunucuya hiç gönderilmez, bu nedenle onları $form->getValues() fonksiyonu tarafından döndürülen verilerde bulamazsınız. Ancak setOmitted(false) ayarlarsanız, Nette bu verilere varsayılan değerlerini dahil eder.

setDisabled() çağrıldığında, güvenlik nedeniyle elemanın değeri silinir. Varsayılan bir değer ayarlıyorsanız, bunu devre dışı bıraktıktan sonra yapmanız gerekir:

$form->addText('username', 'Kullanıcı adı:')
	->setDisabled()
	->setDefaultValue($userName);

Devre dışı bırakılmış elemanlara alternatif olarak, tarayıcının sunucuya gönderdiği readonly HTML niteliğine sahip elemanlar vardır. Eleman yalnızca okunabilir olsa da, değerinin hala bir saldırgan tarafından değiştirilebileceğini veya sahtesinin yapılabileceğini unutmamak önemlidir.

Özel Elemanlar

Geniş yerleşik form elemanları yelpazesinin yanı sıra, forma şu şekilde özel elemanlar ekleyebilirsiniz:

$form->addComponent(new DateInput('Tarih:'), 'date');
// alternatif sözdizimi: $form['date'] = new DateInput('Tarih:');

Form, Container sınıfının bir alt sınıfıdır ve bireysel elemanlar Component sınıfının alt sınıflarıdır.

Özel elemanlar eklemek için formun yeni metotlarını (örneğin $form->addZip()) tanımlamanın bir yolu vardır. Buna extension methods denir. Dezavantajı, editörlerde kod tamamlama özelliğinin onlar için çalışmamasıdır.

use Nette\Forms\Container;

// addZip(string $name, ?string $label = null) metodunu ekliyoruz
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'En az 5 rakam', '[0-9]{5}');
});

// kullanım
$form->addZip('zip', 'Posta kodu:');

Düşük Seviyeli Elemanlar

Yalnızca şablonda yazdığımız ve $form->addXyz() metotlarından biriyle forma eklemediğimiz elemanları da kullanabilirsiniz. Örneğin, veritabanından kayıtları listelerken ve kaç tane olacağını ve ID'lerinin ne olacağını önceden bilmediğimizde ve her satırda bir onay kutusu veya radyo düğmesi görüntülemek istediğimizde, onu şablonda kodlamak yeterlidir:

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

Ve gönderdikten sonra değeri öğreniriz:

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

burada ilk parametre eleman türüdür (DataFile type=file için, DataLine text, password, email vb. gibi tek satırlık girdiler için ve DataText diğer tümü için) ve ikinci parametre sel[] HTML name niteliğine karşılık gelir. Eleman türünü, elemanların anahtarlarını koruyan DataKeys değeriyle birleştirebiliriz. Bu özellikle select, radioList ve checkboxList için kullanışlıdır.

Önemli olan, getHttpData()'nın temizlenmiş bir değer döndürmesidir, bu durumda her zaman geçerli UTF-8 dizelerinden oluşan bir dizi olacaktır, saldırgan sunucuya ne göndermeye çalışırsa çalışsın. Bu, doğrudan $_POST veya $_GET ile çalışmaya benzer, ancak önemli farkla her zaman temiz veriler döndürmesidir, tıpkı standart Nette form elemanlarında alıştığınız gibi.