Nyomtatvány vezérlők
A beépített űrlapvezérlők áttekintése.
addText(string|int $name, $label=null): TextInput
Egysoros szövegmező hozzáadása ( TextInput osztály). Ha a felhasználó nem
tölti ki a mezőt, akkor egy üres karakterláncot ad vissza ''
, vagy a setNullable()
segítségével
megváltoztatja, hogy null
adjon vissza.
$form->addText('name', 'Name:')
->setRequired()
->setNullable();
Automatikusan érvényesíti az UTF-8 szabványt, levágja a bal és jobb oldali fehérjeleket, és eltávolítja a támadó által küldhető sortöréseket.
A maximális hossz a setMaxLength()
segítségével korlátozható. Az addFilter() lehetővé teszi a felhasználó
által megadott érték megváltoztatását.
A setHtmlType()
segítségével a search
, tel
, url
, range
,
date
, datetime-local
, month
, time
, week
, color
beviteli elem karakterét módosíthatja. A
number
és email
típusok helyett az addInteger és az addEmail típusok használatát javasoljuk, amelyek szerveroldali érvényesítést biztosítanak.
$form->addText('color', 'Choose color:')
->setHtmlType('color')
->addRule($form::Pattern, 'invalid value', '[0-9a-f]{6}');
Az elemhez beállítható az úgynevezett üres-érték, ami valami olyasmi, mint az alapértelmezett érték, de ha a
felhasználó nem írja felül, akkor üres stringet vagy null
ad vissza.
$form->addText('phone', 'Phone:')
->setHtmlType('tel')
->setEmptyValue('+420');
addTextArea(string|int $name, $label=null): TextArea
Hozzáad egy többsoros szövegmezőt ( TextArea osztály). Ha a felhasználó nem tölti
ki a mezőt, akkor egy üres karakterláncot ad vissza ''
, vagy a setNullable()
segítségével
megváltoztatja, hogy null
adjon vissza.
$form->addTextArea('note', 'Note:')
->addRule($form::MaxLength, 'Your note is way too long', 10000);
Automatikusan érvényesíti az UTF-8 formátumot és normalizálja a sortöréseket a \n
. Az egysoros beviteli
mezővel ellentétben nem vágja le a szóközöket.
A maximális hossz a setMaxLength()
segítségével korlátozható. Az addFilter() lehetővé teszi a felhasználó
által beírt érték megváltoztatását. Az úgynevezett üres értéket a setEmptyValue()
segítségével
állíthatja be.
addInteger(string|int $name, $label=null): TextInput
Egész számok beviteli mezőjének hozzáadása ( TextInput osztály). Egész számot vagy a
null
értéket adja vissza, ha a felhasználó nem ad meg semmit.
$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
E-mail cím mező hozzáadása érvényességi ellenőrzéssel ( TextInput osztály). Ha a felhasználó nem
tölti ki a mezőt, akkor egy üres karakterláncot ad vissza ''
, vagy a setNullable()
segítségével
megváltoztatja, hogy null
adjon vissza.
$form->addEmail('email', 'Email:');
Ellenőrzi, hogy az érték érvényes e-mail cím-e. Nem ellenőrzi, hogy a domain valóban létezik-e, csak a szintaxisát ellenőrzi. Automatikusan érvényesíti az UTF-8 szabványt, a bal és jobb oldali fehérjeleket levágja.
A maximális hossz a setMaxLength()
segítségével korlátozható. Az addFilter() lehetővé teszi a felhasználó
által megadott érték megváltoztatását. Az úgynevezett üres értéket a setEmptyValue()
segítségével
állíthatja be.
addPassword(string|int $name, $label=null): TextInput
Jelszó mező hozzáadása ( TextInput osztály).
$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].*');
Amikor újra elküldi az űrlapot, a bevitel üres lesz. Automatikusan érvényesíti az UTF-8 kódot, levágja a bal és jobb oldali fehérjeleket, és eltávolítja a támadó által küldhető sortöréseket.
addCheckbox(string|int $name, $caption=null): Checkbox
Hozzáad egy jelölőnégyzetet ( Checkbox
osztály). A mező a true
vagy a false
címet adja vissza, attól függően, hogy be van-e
jelölve.
$form->addCheckbox('agree', 'I agree with terms')
->setRequired('You must agree with our terms');
addCheckboxList(string|int $name, $label=null, array $items=null): CheckboxList
Több elem kiválasztására szolgáló jelölőnégyzetek listájának hozzáadása ( CheckboxList osztály). Visszaadja a
kiválasztott elemek kulcsainak tömbjét. A getSelectedItems()
módszer kulcsok helyett értékeket ad vissza.
$form->addCheckboxList('colors', 'Colors:', [
'r' => 'red',
'g' => 'green',
'b' => 'blue',
]);
Az elemek tömbjét harmadik paraméterként, vagy a setItems()
módszerrel adjuk át.
Használhatja a setDisabled(['r', 'g'])
az egyes elemek letiltására.
Az elem automatikusan ellenőrzi, hogy nem történt-e hamisítás, és hogy a kiválasztott elemek valóban a felkínált
elemek közé tartoznak-e, és nem lettek-e letiltva. A getRawValue()
módszerrel a beküldött elemek e fontos
ellenőrzés nélkül is lekérdezhetők.
Alapértelmezett értékek beállítása esetén azt is ellenőrzi, hogy azok a felkínált elemek közé tartoznak-e,
ellenkező esetben kivételt dob. Ez az ellenőrzés kikapcsolható a checkDefaultValue(false)
segítségével.
addRadioList(string|int $name, $label=null, array $items=null): RadioList
Rádiógombok hozzáadása ( RadioList
osztály). Visszaadja a kiválasztott elem kulcsát, vagy null
, ha a felhasználó nem választott ki semmit. A
getSelectedItem()
metódus kulcs helyett értéket ad vissza.
$sex = [
'm' => 'male',
'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);
Az elemek tömbjét harmadik paraméterként adjuk át, vagy a setItems()
módszerrel.
Használhatja a setDisabled(['m'])
az egyes elemek letiltására.
Az elem automatikusan ellenőrzi, hogy nem történt-e hamisítás, és hogy a kiválasztott elem valóban a felkínált elemek
egyike-e, és nem lett-e letiltva. A getRawValue()
módszerrel a beküldött elemet e fontos ellenőrzés nélkül is
lekérdezheti.
Alapértelmezett érték beállítása esetén azt is ellenőrzi, hogy a felajánlott elemek egyike-e, ellenkező esetben
kivételt dob. Ez az ellenőrzés kikapcsolható a checkDefaultValue(false)
segítségével.
addSelect(string|int $name, $label=null, array $items=null): SelectBox
Kijelölő doboz hozzáadása ( SelectBox
osztály). Visszaadja a kiválasztott elem kulcsát, vagy null
, ha a felhasználó nem választott ki semmit. A
getSelectedItem()
metódus kulcs helyett értéket ad vissza.
$countries = [
'CZ' => 'Czech republic',
'SK' => 'Slovakia',
'GB' => 'United Kingdom',
];
$form->addSelect('country', 'Country:', $countries)
->setDefaultValue('SK');
Az elemek tömbjét harmadik paraméterként adjuk át, vagy a setItems()
módszerrel. Az elemek tömbje lehet
kétdimenziós is:
$countries = [
'Europe' => [
'CZ' => 'Czech republic',
'SK' => 'Slovakia',
'GB' => 'United Kingdom',
],
'CA' => 'Canada',
'US' => 'USA',
'?' => 'other',
];
A kiválasztó dobozok esetében az első elemnek gyakran különleges jelentősége van, ez a call-to-action funkciót látja
el. Ilyen bejegyzés hozzáadásához használja a setPrompt()
módszert.
$form->addSelect('country', 'Country:', $countries)
->setPrompt('Pick a country');
Használhatja a setDisabled(['CZ', 'SK'])
az egyes elemek letiltására.
Az elem automatikusan ellenőrzi, hogy nem történt-e hamisítás, és hogy a kiválasztott elem valóban a felkínált elemek
egyike-e, és nem lett-e letiltva. A getRawValue()
módszerrel a beküldött elemet e fontos ellenőrzés nélkül is
lekérdezheti.
Alapértelmezett érték beállítása esetén azt is ellenőrzi, hogy a felajánlott elemek egyike-e, ellenkező esetben
kivételt dob. Ez az ellenőrzés kikapcsolható a checkDefaultValue(false)
segítségével.
addMultiSelect(string|int $name, $label=null, array $items=null): MultiSelectBox
Hozzáadja a többválasztós kiválasztó dobozt ( MultiSelectBox osztály). Visszaadja a
kiválasztott elemek kulcsainak tömbjét. A getSelectedItems()
módszer kulcsok helyett értékeket ad vissza.
$form->addMultiSelect('countries', 'Countries:', $countries);
Az elemek tömbjét harmadik paraméterként, vagy a setItems()
módszerrel adjuk át. Az elemek tömbje lehet
kétdimenziós is.
Használhatja a setDisabled(['CZ', 'SK'])
az egyes elemek letiltására.
Az elem automatikusan ellenőrzi, hogy nem történt-e hamisítás, és hogy a kiválasztott elemek valóban a felkínált
elemek közé tartoznak-e, és nem lettek-e letiltva. A getRawValue()
módszerrel a beküldött elemek e fontos
ellenőrzés nélkül is lekérdezhetők.
Alapértelmezett értékek beállítása esetén azt is ellenőrzi, hogy azok a felkínált elemek közé tartoznak-e,
ellenkező esetben kivételt dob. Ez az ellenőrzés kikapcsolható a checkDefaultValue(false)
segítségével.
addUpload(string|int $name, $label=null): UploadControl
Fájlfeltöltő mező hozzáadása ( UploadControl osztály). Visszaadja a FileUpload objektumot, még akkor is, ha a felhasználó nem
töltött fel fájlt, amit a FileUpload::hasFile()
metódussal lehet kideríteni.
$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);
Ha a fájl feltöltése nem volt megfelelő, akkor az űrlap nem lett sikeresen elküldve, és hibaüzenet jelenik meg. Vagyis
nem szükséges a FileUpload::isOk()
metódus ellenőrzésére.
Ne bízzon a FileUpload::getName()
módszer által visszaküldött eredeti fájlnévben, az ügyfél
rosszindulatú fájlnevet küldhet azzal a szándékkal, hogy megrongálja vagy feltörje az alkalmazást.
A MimeType
és a Image
szabályok az aláírás alapján ismerik fel a kívánt fájl- vagy
képtípust. A teljes fájl sértetlenségét nem ellenőrzik. Azt, hogy egy kép nem sérült-e, például a betöltési próbálkozással állapíthatja meg.
addMultiUpload(string|int $name, $label=null): UploadControl
Több fájlfeltöltő mező hozzáadása ( UploadControl osztály). Visszaadja a FileUpload objektumok tömbjét. A
FileUpload::hasFile()
metódus mindegyikükhöz a true
metódust adja vissza.
$form->addMultiUpload('files', 'Files:')
->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);
Ha az egyik fájl feltöltése nem sikerül megfelelően, akkor az űrlapot nem sikeresen küldték el, és hibaüzenet jelenik
meg. Vagyis nem szükséges ellenőrizni a FileUpload::isOk()
metódust.
Ne bízzon a FileUpload::getName()
módszer által visszaküldött eredeti fájlnevekben, egy ügyfél
rosszindulatú fájlnevet küldhet azzal a szándékkal, hogy megrongálja vagy feltörje az alkalmazást.
A MimeType
és a Image
szabályok az aláírás alapján ismerik fel a kívánt fájl- vagy
képtípust. A teljes fájl sértetlenségét nem ellenőrzik. Azt, hogy egy kép nem sérült-e, például a betöltési próbálkozással állapíthatja meg.
addHidden(string|int $name, string $default=null): HiddenField
Rejtett mező hozzáadása ( HiddenField osztály).
$form->addHidden('userid');
Használja a setNullable()
címet, hogy üres karakterlánc helyett null
-t adjon vissza. Az addFilter() lehetővé teszi a beküldött érték
megváltoztatását.
addSubmit(string|int $name, $caption=null): SubmitButton
Hozzáadja a submit gombot ( SubmitButton osztály).
$form->addSubmit('submit', 'Register');
Lehetséges, hogy egynél több submit gomb legyen az űrlapon:
$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');
Ahhoz, hogy megtudja, melyikre kattintottak, használja a következőt:
if ($form['register']->isSubmittedBy()) {
// ...
}
Ha nem akarja érvényesíteni az űrlapot, amikor egy beküldő gombot megnyomnak (például a Cancel vagy Preview gombokat), akkor a setValidationScope() segítségével kikapcsolhatja.
addButton(string|int $name, $caption): Button
Hozzáad egy gombot ( Button osztály) submit funkció nélkül. Hasznos más funkciók id-hez kötéséhez, például egy JavaScript művelethez.
$form->addButton('raise', 'Raise salary')
->setHtmlAttribute('onclick', 'raiseSalary()');
addImageButton(string|int $name, string $src=null, string $alt=null): ImageButton
Hozzáadja a submit gombot kép formájában ( ImageButton osztály).
$form->addImageButton('submit', '/path/to/image');
Több submit gomb használata esetén megtudhatja, hogy melyikre kattintott a
$form['submit']->isSubmittedBy()
.
addContainer(string|int $name): Container
Hozzáad egy al-űrlapot ( Container osztály),
vagy konténert, amely ugyanúgy kezelhető, mint egy űrlap. Ez azt jelenti, hogy használhatja az olyan módszereket, mint a
setDefaults()
vagy a getValues()
.
$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:');
Az elküldött adatokat ezután többdimenziós struktúraként adja vissza:
[
'first' => [
'name' => /* ... */,
'email' => /* ... */,
],
'second' => [
'name' => /* ... */,
'email' => /* ... */,
],
]
A beállítások áttekintése
Minden elemhez a következő metódusokat hívhatjuk meg (a teljes áttekintésért lásd az API dokumentációt ):
setDefaultValue($value) |
az alapértelmezett érték beállítása |
getValue() |
aktuális érték lekérése |
setOmitted() |
kihagyott értékek |
setDisabled() |
bemenetek letiltása |
Renderelés:
setCaption($caption) |
az elem feliratának módosítása |
setTranslator($translator) |
fordító beállítása |
setHtmlAttribute($name, $value) |
beállítja az elem HTML-attribútumát. |
setHtmlId($id) |
beállítja a HTML-attribútumot id |
setHtmlType($type) |
HTML-attribútum beállítása type |
setHtmlName($name) |
HTML-attribútum beállítása name |
setOption($key, $value) |
beállítja a renderelési adatokat |
Érvényesítés:
setRequired() |
kötelező mező |
addRule() |
érvényesítési szabály beállítása |
addCondition() , addConditionOn() |
érvényesítési feltétel beállítása |
addError($message) |
hibaüzenet átadása |
A következő metódusok hívhatók a addText()
, addPassword()
, addTextArea()
,
addEmail()
, addInteger()
elemekhez:
setNullable() |
beállítja, hogy a getValue() az üres karakterlánc helyett a null értéket adja-e vissza. |
setEmptyValue($value) |
beállítja a speciális értéket, amelyet üres karakterláncként kezel. |
setMaxLength($length) |
beállítja a megengedett karakterek maximális számát. |
addFilter($filter) |
bemeneti értékek módosítása |
Kihagyott értékek
Ha nem érdekel a felhasználó által megadott érték, a setOmitted()
segítségével kihagyhatjuk azt a
$form->getValues()
metódus által szolgáltatott vagy a kezelőknek átadott eredményből. Ez alkalmas
különböző jelszavak ellenőrzésére, spamellenes mezőkhöz stb.
$form->addPassword('passwordVerify', 'Password again:')
->setRequired('Fill your password again to check for typo')
->addRule($form::Equal, 'Password mismatch', $form['password'])
->setOmitted();
Bemenetek letiltása
Egy bemenet letiltásához hívja a setDisabled()
címet. Az ilyen mezőt a felhasználó nem szerkesztheti.
$form->addText('username', 'User name:')
->setDisabled();
Vegye figyelembe, hogy a böngésző egyáltalán nem küldi el a letiltott mezőket a szerverre, így a
$form->getValues()
függvény által visszaküldött adatokban sem fogja megtalálni őket.
Ha alapértelmezett értéket állít be egy mezőhöz, akkor ezt csak a mező letiltása után szabad megtennie:
$form->addText('username', 'User name:')
->setDisabled()
->setDefaultValue($userName);
Egyéni vezérlők
A beépített űrlapvezérlők széles skálája mellett egyéni vezérlőket is hozzáadhat az űrlaphoz az alábbiak szerint:
$form->addComponent(new DateInput('Date:'), 'date');
// alternatív szintaxis: $form['date'] = new DateInput('Date:');
A form a Container osztály leszármazottja, az elemek pedig a Component osztály leszármazottai.
Van lehetőség új űrlapmódszerek definiálására az egyéni elemek hozzáadásához (pl. $form->addZip()
).
Ezek az úgynevezett kiterjesztési metódusok. Hátrányuk, hogy a szerkesztőkben a kódsegédletek nem működnek ezeknél.
use Nette\Forms\Container;
// adds method addZip(string $name, string $label = null)
Container::extensionMethod('addZip', function (Container $form, string $name, string $label = null) {
return $form->addText($name, $label)
->addRule($form::Pattern, 'Legalább 5 szám', '[0-9]{5}');
});
// használat
$form->addZip('zip', 'Irányítószám:');
Alacsony szintű mezők
Egy elem hozzáadásához az űrlaphoz nem kell meghívni a $form->addXyz()
címet. Az űrlapelemeket ehelyett
kizárólag sablonokban lehet bevezetni. Ez akkor hasznos, ha például dinamikus elemeket kell létrehozni:
{foreach $items as $item}
<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}
A beküldés után lekérdezheti az értékeket:
$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');
Az első paraméterben megadhatja az elem típusát (DataFile
a type=file
, DataLine
az
egysoros bemenetekhez, mint a text
, password
vagy email
és DataText
a
többi). A második paraméter megfelel a name
HTML-attribútumnak. Ha meg kell őrizni a kulcsokat, akkor az első
paramétert kombinálhatja a DataKeys
paraméterrel. Ez a select
, radioList
vagy
checkboxList
esetében hasznos.
A getHttpData()
szanált bemenetet ad vissza. Ebben az esetben mindig érvényes UTF-8-as karakterláncok tömbje
lesz, függetlenül attól, hogy az űrlap által küldött támadó mit küldött. Ez egy alternatívája a $_POST
vagy $_GET
közvetlen munkájának, ha biztonságos adatokat szeretne kapni.