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.
Giriş öğesinin karakterini
search
, tel
, url
, range
, date
, datetime-local
,
month
, time
, week
, color
olarak değiştirmek için setHtmlType()
kullanın. number
ve email
türleri yerine, sunucu tarafı doğrulama sağlayan addInteger ve addEmail'i kullanmanızı öneririz.
$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('level', 'Level:')
->setDefaultValue(0)
->addRule($form::Range, 'Level must be between %d and %d.', [0, 100]);
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.
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();
Tarayıcının devre dışı bırakılan alanları sunucuya göndermediğini unutmayın, bu nedenle bunları
$form->getValues()
işlevi tarafından döndürülen verilerde bile bulamazsınız.
Bir alan için varsayılan bir değer ayarlıyorsanız, bunu yalnızca 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.