Form Kontrolleri

Yerleşik form kontrollerine genel bakış.

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

Tek satırlık metin alanı ekler ( TextInput sınıfı). Kullanıcı alanı doldurmazsa, boş bir dize döndürür '' veya null döndürmek üzere değiştirmek için setNullable() kullanın.

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

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

Maksimum uzunluk setMaxLength() kullanılarak sınırlandırılabilir. addFilter() kullanıcı tarafından girilen değeri değiştirmenize olanak tanır.

Bir metin alanının görsel karakterini, spesifikasyonda görüldüğü gibi setHtmlType() kullanarak search, tel veya url gibi türlere değiştirebilirsiniz. Türü değiştirmenin yalnızca görsel olduğunu ve doğrulama işlevlerini yerine getirmediğini 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 girdi türleri için sunucu tarafı doğrulama sağlayan addInteger, addFloat, addEmail addDate, addTime, addDateTime ve addColor gibi özel yöntemleri kullanın. month ve week türleri henüz tüm tarayıcılarda tam olarak desteklenmemektedir.

Varsayılan değer gibi bir şey olan boş değer öğe için ayarlanabilir, ancak kullanıcı bunun üzerine yazmazsa boş dize veya null döndürür.

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

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

Çok satırlı bir metin alanı ekler ( TextArea sınıfı). Kullanıcı alanı doldurmazsa, boş bir dize döndürür '' veya null döndürmek üzere değiştirmek için setNullable() kullanın.

$form->addTextArea('note', 'Note:')
	->addRule($form::MaxLength, 'Your note is way too long', 10000);

UTF-8'i otomatik olarak doğrular ve satır sonlarını \n olarak normalleştirir. Tek satırlı bir giriş alanının aksine, boşlukları kırpmaz.

Maksimum uzunluk setMaxLength() kullanılarak sınırlandırılabilir. addFilter() kullanıcı tarafından girilen değeri değiştirmenize olanak tanır. Boş değer olarak adlandırılan değeri setEmptyValue() adresini kullanarak ayarlayabilirsiniz.

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

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

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

Öğe şu şekilde oluşturulur <input type="numeric">. setHtmlType() yöntemini kullanarak, kaydırıcı olarak görüntülemek için türü range olarak veya numeric özel davranışı olmadan standart bir metin alanı tercih ediyorsanız text olarak değiştirebilirsiniz.

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('level', 'Level:')
	->setDefaultValue(0)
->addRule($form::Range, 'The level must be in the range %d to %d.', [0, 100 |0, 100]);

Nette ve Chrome tarayıcısı ondalık ayırıcı olarak hem virgül hem de nokta kabul eder. Bu işlevi Firefox'ta kullanılabilir hale getirmek için, örneğin belirli bir öğe veya tüm sayfa için lang özniteliğinin ayarlanması önerilir, <html lang="cs">.

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

Geçerlilik kontrolü ile e-posta adresi alanı ekler (class TextInput). Kullanıcı alanı doldurmazsa, boş bir dize döndürür '' veya null döndürmek üzere değiştirmek için setNullable() kullanın.

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

Değerin geçerli bir e-posta adresi olduğunu doğrular. Etki alanının gerçekten var olduğunu doğrulamaz, 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, $cols, ?int $maxLength=null): TextInput

Parola alanı ekler ( TextInput sınıfı).

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

Formu yeniden gönderdiğinizde, girdi boş olacaktır. UTF-8'i otomatik olarak doğrular, sol ve sağ boşlukları keser ve bir saldırgan tarafından gönderilebilecek satır sonlarını kaldırır.

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

Bir onay kutusu ekler ( Checkbox sınıfı). Alan, işaretli olup olmamasına bağlı olarak true veya false döndürür.

$form->addCheckbox('agree', 'I agree with terms')
	->setRequired('You must agree with our terms');

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

Birden fazla öğe seçmek için onay kutuları listesi ekler (sınıf CheckboxList). Seçilen öğelerin anahtar dizisini döndürür. getSelectedItems() yöntemi anahtarlar yerine değerler döndürür.

$form->addCheckboxList('colors', 'Colors:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);

Öğe dizisini üçüncü parametre olarak veya setItems() yöntemiyle iletiriz.

Kullanabilirsiniz setDisabled(['r', 'g']) tek tek öğeleri devre dışı bırakmak için.

Öğe, 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. Bu önemli kontrol olmadan sunulan öğeleri almak için getRawValue() yöntemi kullanılabilir.

Varsayılan değerler ayarlandığında, bunların sunulan öğelerden biri olup olmadığını da kontrol eder, aksi takdirde bir istisna atar. Bu kontrol checkDefaultValue(false) ile kapatılabilir.

Bir formu GET yöntemini kullanarak gönderiyorsanız, sorgu dizesinin boyutundan tasarruf sağlayan daha kompakt bir veri aktarım yöntemi seçebilirsiniz. Bu, formun HTML özniteliğinin ayarlanmasıyla etkinleştirilir:

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

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

Radyo düğmeleri ekler ( RadioList sınıfı). Seçilen öğenin anahtarını veya kullanıcı herhangi bir şey seçmediyse null adresini döndürür. getSelectedItem() yöntemi, anahtar yerine bir değer döndürür.

$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);

Öğe dizisini üçüncü parametre olarak veya setItems() yöntemiyle iletiriz.

Kullanabilirsiniz setDisabled(['m']) tek tek öğeleri devre dışı bırakmak için.

Öğe, 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. Bu önemli kontrol yapılmadan sunulan öğeyi almak için getRawValue() yöntemi kullanılabilir.

Varsayılan değer ayarlandığında, bunun sunulan öğelerden biri olup olmadığını da kontrol eder, aksi takdirde bir istisna atar. Bu kontrol checkDefaultValue(false) ile kapatılabilir.

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

Seçme kutusu ekler ( SelectBox sınıfı). Seçilen öğenin anahtarını veya kullanıcı herhangi bir şey seçmediyse null adresini döndürür. getSelectedItem() yöntemi, anahtar yerine bir değer döndürür.

$countries = [
	'CZ' => 'Czech republic',
	'SK' => 'Slovakia',
	'GB' => 'United Kingdom',
];

$form->addSelect('country', 'Country:', $countries)
	->setDefaultValue('SK');

Öğe dizisini üçüncü parametre olarak veya setItems() yöntemiyle aktarırız. Öğe dizisi iki boyutlu da olabilir:

$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];

Seçim kutuları için, ilk öğenin genellikle özel bir anlamı vardır, eylem çağrısı görevi görür. Böyle bir girdi eklemek için setPrompt() yöntemini kullanın.

$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');

Kullanabilirsiniz setDisabled(['CZ', 'SK']) tek tek öğeleri devre dışı bırakmak için.

Varsayılan değer ayarlandığında, bunun sunulan öğelerden biri olup olmadığını da kontrol eder, aksi takdirde bir istisna atar. Bu kontrol checkDefaultValue(false) ile kapatılabilir.

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

Çok seçenekli seçim kutusu ekler ( MultiSelectBox sınıfı). Seçilen öğelerin anahtar dizisini döndürür. getSelectedItems() yöntemi anahtarlar yerine değerler döndürür.

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

Öğe dizisini üçüncü parametre olarak veya setItems() yöntemiyle aktarırız. Öğe dizisi iki boyutlu da olabilir.

Kullanabilirsiniz setDisabled(['CZ', 'SK']) tek tek öğeleri devre dışı bırakmak için.

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

Dosya yükleme alanı ekler ( UploadControl sınıfı). Kullanıcı bir dosya yüklememiş olsa bile FileUpload nesnesini döndürür, bu FileUpload::hasFile() yöntemiyle öğrenilebilir.

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

Dosya doğru şekilde yüklenmediyse, form başarıyla gönderilmemiştir ve bir hata görüntülenir. Yani FileUpload::isOk() yöntemini kontrol etmek gerekli değildir.

FileUpload::getName() yöntemi tarafından döndürülen orijinal dosya adına güvenmeyin, bir istemci uygulamanızı bozmak veya hacklemek amacıyla kötü amaçlı bir dosya adı gönderebilir.

Kurallar MimeType ve Image gerekli dosya veya görüntü türünü imzasına göre tespit eder. Tüm dosyanın bütünlüğü kontrol edilmez. Bir görüntünün bozuk olup olmadığını örneğin yüklemeye çalışarak öğrenebilirsiniz.

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

Çoklu dosya yükleme alanı ekler ( UploadControl sınıfı). FileUpload nesnelerinden oluşan bir dizi döndürür. FileUpload::hasFile() yöntemi her biri için true döndürür.

$form->addMultiUpload('files', 'Files:')
	->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);

Dosyalardan biri doğru şekilde yüklenemezse, form başarıyla gönderilmemiştir ve bir hata görüntülenir. Yani FileUpload::isOk() yöntemini kontrol etmek gerekli değildir.

FileUpload::getName() yöntemi tarafından döndürülen orijinal dosya adlarına güvenmeyin, bir istemci uygulamanızı bozmak veya hacklemek amacıyla kötü amaçlı bir dosya adı gönderebilir.

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 ( DateTimeControl sınıfı).

Varsayılan değer için, DateTimeInterface adresini 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 kural bağımsız değişkenleri için de geçerlidir.

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

Varsayılan olarak, bir DateTimeImmutable nesnesi döndürür. setFormat() yöntemini kullanarak bir metin biçimi veya zaman damgası belirtebilirsiniz:

$form->addDate('date', 'Date:')
	->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 saniyelerden oluşan zamanı kolayca girmesini sağlayan bir alan ekler ( DateTimeControl sınıfı).

Varsayılan değer için, DateTimeInterface adresini 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 kural bağımsız değişkenleri için de geçerlidir. Ayarlanan minimum değer maksimum değerden yüksekse, gece yarısını kapsayan bir zaman aralığı oluşturulur.

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

Varsayılan olarak, bir DateTimeImmutable nesnesi döndürür (tarih 1 Ocak, yıl 1). setFormat() yöntemini kullanarak bir metin biçimi belirtebilirsiniz:

$form->addTime('time', 'Time:')
	->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 tarih ve saati kolayca girmesini sağlayan bir alan ekler ( DateTimeControl sınıfı).

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

Varsayılan olarak, bir DateTimeImmutable nesnesi döndürür. setFormat() yöntemini kullanarak bir metin biçimi veya zaman damgası belirtebilirsiniz:

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

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

Bir renk seçim alanı ekler ( ColorPicker sınıfı). Renk, #rrggbb biçiminde bir dizedir. Kullanıcı bir seçim yapmazsa, döndürülen varsayılan renk siyahtır #000000.

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

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

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

$form->addHidden('userid');

Boş bir dize yerine null döndürmek üzere değiştirmek için setNullable() adresini kullanın. addFilter(), gönderilen değeri değiştirmenize olanak tanır.

Öğe gizli olsa da, değerinin bir saldırgan tarafından değiştirilebileceğini veya yanıltılabileceğini fark etmek önemlidir. Veri manipülasyonuyla ilişkili güvenlik risklerini önlemek için sunucu tarafında alınan tüm değerleri her zaman kapsamlı bir şekilde doğrulayın ve onaylayın.

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

Gönder düğmesi ekler ( SubmitButton sınıfı).

$form->addSubmit('submit', 'Register');

Formda birden fazla gönder düğmesi olması mümkündür:

$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');

Hangisinin tıklandığını bulmak için şunu kullanın:

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

Bir gönder düğmesine basıldığında (İptal veya Önizleme düğmeleri gibi) formu doğrulamak istemiyorsanız, setValidationScope() ile bunu kapatabilirsiniz.

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

Gönderme işlevi olmayan düğme ( Button sınıfı) ekler. Diğer işlevleri id'ye bağlamak için kullanışlıdır, örneğin bir JavaScript eylemi.

$form->addButton('raise', 'Raise salary')
	->setHtmlAttribute('onclick', 'raiseSalary()');

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

Resim biçiminde gönder düğmesi ekler ( ImageButton sınıfı).

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

Birden fazla gönder düğmesi kullanırken, hangisinin tıklandığını şu şekilde öğrenebilirsiniz $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Bir alt form ( Container sınıfı) veya bir formla aynı şekilde ele alınabilen bir konteyner ekler. Bu, setDefaults() veya getValues() gibi yöntemleri kullanabileceğiniz anlamına gelir.

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

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

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

Ayarlara Genel Bakış

Tüm öğeler için aşağıdaki yöntemleri çağırabiliriz (tam bir genel bakış için API belgelerine bakın):

`setDefaultValue($value)`	varsayılan değeri ayarlar
`getValue()`	mevcut değeri al
`setOmitted()`	atlanan değerler
`setDisabled()`	girişleridevre dışı bırakma

Rendeleme:

`setCaption($caption)`	öğenin başlığını değiştir
`setTranslator($translator)`	çevirmeni ayarlar
`setHtmlAttribute($name, $value)`	öğenin HTML niteliğini ayarlar
`setHtmlId($id)`	HTML niteliğini ayarlar `id`
`setHtmlType($type)`	HTML özniteliğini ayarlar `type`
`setHtmlName($name)`	HTML özniteliğini ayarlar `name`
`setOption($key, $value)`	render verilerini ayarlar

Doğrulama:

`setRequired()`	zorunlu alan
`addRule()`	doğrulama kuralını ayarla
`addCondition()`, `addConditionOn()`	doğrulama koşulunu ayarla
`addError($message)`	hata mesajı iletme

Aşağıdaki yöntemler addText(), addPassword(), addTextArea(), addEmail(), addInteger() öğeleri için çağrılabilir:

`setNullable()`	getValue() işlevinin boş dize yerine `null` döndürüp döndürmeyeceğini ayarlar
`setEmptyValue($value)`	boş dize olarak kabul edilen özel değeri ayarlar
`setMaxLength($length)`	izin verilen maksimum karakter sayısını ayarlar
`addFilter($filter)`	Girdi Değerlerini Değiştirme

Atlanan Değerler

Kullanıcı tarafından girilen değerle ilgilenmiyorsanız, $form->getValues() yöntemi tarafından sağlanan veya işleyicilere aktarılan sonuçtan çıkarmak için setOmitted() adresini kullanabiliriz. Bu, doğrulama için çeşitli parolalar, antispam alanları vb. için uygundur.

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

Girişleri Devre Dışı Bırakma

Girişler setDisabled() kullanılarak devre dışı bırakılabilir. Devre dışı bırakılan bir girdi kullanıcı tarafından düzenlenemez.

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

Devre dışı bırakılan girişler tarayıcı tarafından sunucuya gönderilmez, bu nedenle $form->getValues() işlevi tarafından döndürülen verilerde bunları bulamazsınız. Ancak, setOmitted(false) adresini ayarlarsanız, Nette varsayılan değerlerini bu verilere dahil edecektir.

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

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

Devre dışı bırakılmış girdilere alternatif olarak, tarayıcı tarafından sunucuya gönderilen HTML readonly özniteliğine sahip alanlar kullanılabilir. Alan yalnızca okunabilir olsa da, değerinin bir saldırgan tarafından değiştirilebileceğini veya yanıltılabileceğini fark etmek önemlidir.

Özel Kontroller

Çok çeşitli yerleşik form kontrollerinin yanı sıra, forma aşağıdaki gibi özel kontroller ekleyebilirsiniz:

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

Form, Container sınıfının bir torunudur ve elemanlar Component'in torunlarıdır.

Özel öğeler eklemek için yeni form yöntemleri tanımlamanın bir yolu vardır (örneğin $form->addZip()). Bunlar uzantı yöntemleri olarak adlandırılır. Dezavantajı, editörlerdeki kod ipuçlarının bunlar için çalışmayacağıdır.

use Nette\Forms\Container;

// addZip(string $name, ?string $label = null) yöntemini ekler
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'At least 5 numbers', '[0-9]{5}');
});

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

Düşük Seviyeli Alanlar

Forma bir öğe eklemek için $form->addXyz() adresini çağırmak zorunda değilsiniz. Bunun yerine form öğeleri yalnızca şablonlarda tanıtılabilir. Bu, örneğin dinamik öğeler oluşturmanız gerekiyorsa kullanışlıdır:

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

Gönderdikten sonra değerleri alabilirsiniz:

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

İlk parametrede, öğe türünü belirtirsiniz ( type=file içinDataFile, text, password veya email gibi tek satırlı girdiler için DataLine ve diğerleri için DataText ). İkinci parametre name HTML özniteliğiyle eşleşir. Anahtarları korumanız gerekiyorsa, ilk parametreyi DataKeys ile birleştirebilirsiniz. Bu select, radioList veya checkboxList için kullanışlıdır.

getHttpData() temizlenmiş girdi döndürür. Bu durumda, form tarafından gönderilen saldırgan ne olursa olsun, her zaman geçerli UTF-8 dizeleri dizisi olacaktır. Güvenli veri almak istiyorsanız doğrudan $_POST veya $_GET ile çalışmaya bir alternatiftir.