Form Kontrolleri

Yerleşik form kontrollerine genel bakış.

addText(string|int $name, $label=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.

setHtmlType() adresini kullanarak giriş öğesinin karakterini search, tel, url, range, month, week veya color olarak değiştirebilirsiniz. number , email, date, datetime-local ve time gibi diğer türler için, sunucu tarafı doğrulama ile birlikte gelen addInteger, addFloat, addEmail, addDate, addTime ve addDateTime ayrı yöntemleri vardır.

$form->addText('color', 'Choose color:')
	->setHtmlType('color')
	->addRule($form::Pattern, 'invalid value', '[0-9a-f]{6}');

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

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 ondalık ayırıcı olarak hem virgül hem de noktayı kabul eder. Firefox'un da virgül kabul etmesi için, ilgili dili lang HTML niteliğinde, doğrudan bu öğeye veya herhangi bir üst öğeye ayarlamanız gerekir, örneğin <html lang="cs">.

addEmail(string|int $name, $label=null): 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.

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.

addPassword(string|int $name, $label=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.

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): 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.

Öğ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.

addMultiSelect(string|int $name, $label=null, array $items=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.

Öğ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.

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.

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.

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ı).

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->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.

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

Bir girişi devre dışı bırakmak için setDisabled() adresini çağırabilirsiniz. Böyle bir alan kullanıcı tarafından düzenlenemez.

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

Devre dışı bırakılan alanlar 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 bunların değerini bu veriye dahil edecektir.

setDisabled() adresini çağırdığınızda, alanın değeri silinir. Varsayılan bir değer ayarlıyorsanız, bunu devre dışı bıraktıktan sonra yapmalısınız:

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

Ö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.

versiyon: 4.0