Formular-Steuerelemente
Übersicht über die eingebauten Formularsteuerelemente.
addText(string|int $name, $label=null): TextInput
Fügt ein einzeiliges Textfeld hinzu (Klasse TextInput). Wenn der Benutzer das Feld nicht
ausfüllt, wird eine leere Zeichenkette ''
zurückgegeben, oder verwenden Sie setNullable()
, um dies zu
ändern und null
zurückzugeben.
$form->addText('name', 'Name:')
->setRequired()
->setNullable();
Es validiert automatisch UTF-8, schneidet linke und rechte Leerzeichen ab und entfernt Zeilenumbrüche, die von einem Angreifer gesendet werden könnten.
Die maximale Länge kann mit setMaxLength()
begrenzt werden. Mit addFilter() können Sie den vom Benutzer
eingegebenen Wert ändern.
Verwenden Sie setHtmlType()
, um das Zeichen des Eingabeelements in
search
, tel
, url
, range
, date
, datetime-local
,
month
, time
, week
, color
zu ändern. Anstelle der Typen number
und email
empfehlen wir die Verwendung von addInteger und addEmail, die eine serverseitige Validierung ermöglichen.
$form->addText('color', 'Choose color:')
->setHtmlType('color')
->addRule($form::Pattern, 'invalid value', '[0-9a-f]{6}');
Für das Element kann der sogenannte empty-value gesetzt werden, der so etwas wie der Standardwert ist, aber, wenn der Benutzer
ihn nicht überschreibt, einen leeren String oder null
zurückgibt.
$form->addText('phone', 'Phone:')
->setHtmlType('tel')
->setEmptyValue('+420');
addTextArea(string|int $name, $label=null): TextArea
Fügt ein mehrzeiliges Textfeld (Klasse TextArea) hinzu. Wenn der Benutzer das Feld nicht
ausfüllt, wird eine leere Zeichenkette ''
zurückgegeben, oder verwenden Sie setNullable()
, um dies zu
ändern und null
zurückzugeben.
$form->addTextArea('note', 'Note:')
->addRule($form::MaxLength, 'Your note is way too long', 10000);
Validiert automatisch UTF-8 und normalisiert Zeilenumbrüche auf \n
. Im Gegensatz zu einem einzeiligen
Eingabefeld wird der Leerraum nicht abgeschnitten.
Die maximale Länge kann mit setMaxLength()
begrenzt werden. Mit addFilter() können Sie den vom Benutzer
eingegebenen Wert ändern. Mit setEmptyValue()
können Sie den sogenannten Leerwert setzen.
addInteger(string|int $name, $label=null): TextInput
Fügt Eingabefeld für Ganzzahl (Klasse TextInput) hinzu. Gibt entweder eine Ganzzahl
oder null
zurück, wenn der Benutzer nichts eingibt.
$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
Fügt ein E-Mail-Adressfeld mit Gültigkeitsprüfung hinzu (Klasse TextInput). Wenn der Benutzer das Feld nicht
ausfüllt, wird eine leere Zeichenkette ''
zurückgegeben, oder verwenden Sie setNullable()
, um dies zu
ändern und null
zurückzugeben.
$form->addEmail('email', 'Email:');
Überprüft, ob der Wert eine gültige E-Mail-Adresse ist. Es wird nicht überprüft, ob die Domäne tatsächlich existiert, nur die Syntax wird überprüft. Validiert automatisch UTF-8, schneidet linke und rechte Leerzeichen ab.
Die maximale Länge kann mit setMaxLength()
begrenzt werden. Mit addFilter() können Sie den vom Benutzer
eingegebenen Wert ändern. Mit setEmptyValue()
können Sie den sogenannten Leerwert setzen.
addPassword(string|int $name, $label=null): TextInput
Fügt Passwortfeld hinzu (Klasse TextInput).
$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].*');
Wenn Sie das Formular erneut absenden, ist die Eingabe leer. Es validiert automatisch UTF-8, schneidet linke und rechte Leerzeichen ab und entfernt Zeilenumbrüche, die von einem Angreifer gesendet werden könnten.
addCheckbox(string|int $name, $caption=null): Checkbox
Fügt ein Kontrollkästchen (Klasse Checkbox) hinzu. Das Feld gibt entweder
true
oder false
zurück, je nachdem, ob es markiert ist.
$form->addCheckbox('agree', 'I agree with terms')
->setRequired('You must agree with our terms');
addCheckboxList(string|int $name, $label=null, array $items=null): CheckboxList
Fügt eine Liste von Kontrollkästchen zur Auswahl mehrerer Elemente hinzu (Klasse CheckboxList). Gibt das Array der Schlüssel
der ausgewählten Elemente zurück. Die Methode getSelectedItems()
gibt Werte anstelle von Schlüsseln zurück.
$form->addCheckboxList('colors', 'Colors:', [
'r' => 'red',
'g' => 'green',
'b' => 'blue',
]);
Wir übergeben das Array der Elemente als dritten Parameter oder mit der Methode setItems()
.
Sie können mit setDisabled(['r', 'g'])
verwenden, um einzelne Elemente zu deaktivieren.
Das Element überprüft automatisch, dass keine Fälschung vorliegt und dass die ausgewählten Einträge tatsächlich zu den
angebotenen gehören und nicht deaktiviert wurden. Die Methode getRawValue()
kann verwendet werden, um eingereichte
Artikel ohne diese wichtige Prüfung abzurufen.
Wenn Standardwerte gesetzt werden, wird auch geprüft, ob sie zu den angebotenen Artikeln gehören, andernfalls wird eine
Ausnahme geworfen. Diese Prüfung kann mit checkDefaultValue(false)
ausgeschaltet werden.
addRadioList(string|int $name, $label=null, array $items=null): RadioList
Fügt Optionsfelder hinzu (Klasse RadioList). Gibt den Schlüssel des
ausgewählten Elements zurück, oder null
, wenn der Benutzer nichts ausgewählt hat. Die Methode
getSelectedItem()
gibt einen Wert statt eines Schlüssels zurück.
$sex = [
'm' => 'male',
'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);
Wir übergeben das Array der Elemente als dritten Parameter oder mit der Methode setItems()
.
Sie können mit setDisabled(['m'])
verwenden, um einzelne Elemente zu deaktivieren.
Das Element überprüft automatisch, dass keine Fälschung vorliegt und dass das ausgewählte Element tatsächlich eines der
angebotenen ist und nicht deaktiviert wurde. Die Methode getRawValue()
kann verwendet werden, um das eingereichte
Element ohne diese wichtige Prüfung abzurufen.
Wenn der Standardwert eingestellt ist, wird auch geprüft, ob es sich um einen der angebotenen Einträge handelt, andernfalls
wird eine Ausnahme ausgelöst. Diese Prüfung kann mit checkDefaultValue(false)
ausgeschaltet werden.
addSelect(string|int $name, $label=null, array $items=null): SelectBox
Fügt ein Auswahlfeld hinzu (Klasse SelectBox). Gibt den Schlüssel des
ausgewählten Elements zurück, oder null
, wenn der Benutzer nichts ausgewählt hat. Die Methode
getSelectedItem()
gibt einen Wert statt eines Schlüssels zurück.
$countries = [
'CZ' => 'Czech republic',
'SK' => 'Slovakia',
'GB' => 'United Kingdom',
];
$form->addSelect('country', 'Country:', $countries)
->setDefaultValue('SK');
Wir übergeben das Array der Elemente als dritten Parameter oder mit der Methode setItems()
. Das Array der
Elemente kann auch zweidimensional sein:
$countries = [
'Europe' => [
'CZ' => 'Czech republic',
'SK' => 'Slovakia',
'GB' => 'United Kingdom',
],
'CA' => 'Canada',
'US' => 'USA',
'?' => 'other',
];
Bei Auswahlfeldern hat der erste Eintrag oft eine besondere Bedeutung, er dient als Call-to-Action. Verwenden Sie die Methode
setPrompt()
, um einen solchen Eintrag hinzuzufügen.
$form->addSelect('country', 'Country:', $countries)
->setPrompt('Pick a country');
Sie können mit setDisabled(['CZ', 'SK'])
können Sie einzelne Einträge deaktivieren.
Das Element prüft automatisch, dass keine Fälschung vorliegt und dass das ausgewählte Element tatsächlich eines der
angebotenen ist und nicht deaktiviert wurde. Die Methode getRawValue()
kann verwendet werden, um das eingereichte
Element ohne diese wichtige Prüfung abzurufen.
Wenn der Standardwert eingestellt ist, wird auch geprüft, ob es sich um einen der angebotenen Einträge handelt, andernfalls
wird eine Ausnahme ausgelöst. Diese Prüfung kann mit checkDefaultValue(false)
ausgeschaltet werden.
addMultiSelect(string|int $name, $label=null, array $items=null): MultiSelectBox
Fügt ein Auswahlfeld mit mehreren Auswahlmöglichkeiten hinzu (Klasse MultiSelectBox). Gibt das Array der
Schlüssel der ausgewählten Elemente zurück. Die Methode getSelectedItems()
gibt Werte anstelle von Schlüsseln
zurück.
$form->addMultiSelect('countries', 'Countries:', $countries);
Wir übergeben das Array der Elemente als dritten Parameter oder mit der Methode setItems()
. Das Array der
Elemente kann auch zweidimensional sein.
Sie können mit setDisabled(['CZ', 'SK'])
verwenden, um einzelne Elemente zu deaktivieren.
Das Element prüft automatisch, dass keine Fälschung vorliegt und dass die ausgewählten Einträge tatsächlich zu den
angebotenen gehören und nicht deaktiviert wurden. Die Methode getRawValue()
kann verwendet werden, um eingereichte
Artikel ohne diese wichtige Prüfung abzurufen.
Wenn Standardwerte gesetzt werden, wird auch geprüft, ob sie zu den angebotenen Artikeln gehören, andernfalls wird eine
Ausnahme geworfen. Diese Prüfung kann mit checkDefaultValue(false)
ausgeschaltet werden.
addUpload(string|int $name, $label=null): UploadControl
Fügt ein Datei-Upload-Feld hinzu (Klasse UploadControl). Gibt das FileUpload-Objekt zurück, auch wenn der Benutzer keine Datei
hochgeladen hat, was mit der Methode FileUpload::hasFile()
herausgefunden werden kann.
$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);
Wenn die Datei nicht korrekt hochgeladen wurde, wurde das Formular nicht erfolgreich abgeschickt und es wird ein Fehler
angezeigt. D.h. es ist nicht notwendig, die Methode FileUpload::isOk()
zu überprüfen.
Vertrauen Sie nicht auf den ursprünglichen Dateinamen, der von der Methode FileUpload::getName()
zurückgegeben wird.
Die Regeln MimeType
und Image
erkennen den gewünschten Typ einer Datei oder eines Bildes anhand
ihrer Signatur. Die Integrität der gesamten Datei wird nicht geprüft. Sie können herausfinden, ob ein Bild nicht beschädigt
ist, indem Sie beispielsweise versuchen, es zu laden.
addMultiUpload(string|int $name, $label=null): UploadControl
Fügt ein Feld zum Hochladen mehrerer Dateien hinzu (Klasse UploadControl). Gibt ein Array von Objekten
FileUpload zurück. Die Methode
FileUpload::hasFile()
gibt true
für jedes dieser Objekte zurück.
$form->addMultiUpload('files', 'Files:')
->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);
Wenn eine der Dateien nicht korrekt hochgeladen werden kann, wurde das Formular nicht erfolgreich übermittelt und es wird ein
Fehler angezeigt. Es ist also nicht notwendig, die Methode FileUpload::isOk()
zu überprüfen.
Vertrauen Sie nicht auf die von der Methode FileUpload::getName()
zurückgegebenen Originaldateinamen. Ein Client
könnte einen bösartigen Dateinamen mit der Absicht senden, Ihre Anwendung zu beschädigen oder zu hacken.
Die Regeln MimeType
und Image
erkennen den gewünschten Typ einer Datei oder eines Bildes anhand
ihrer Signatur. Die Integrität der gesamten Datei wird nicht geprüft. Sie können herausfinden, ob ein Bild nicht beschädigt
ist, indem Sie beispielsweise versuchen, es zu laden.
addHidden(string|int $name, string $default=null): HiddenField
Fügt ein verstecktes Feld (Klasse HiddenField) hinzu.
$form->addHidden('userid');
Verwenden Sie setNullable()
, um die Rückgabe von null
anstelle eines leeren Strings zu ändern. Mit
addFilter() können Sie den übergebenen Wert
ändern.
addSubmit(string|int $name, $caption=null): SubmitButton
Fügt die Schaltfläche Submit (Klasse SubmitButton) hinzu.
$form->addSubmit('submit', 'Register');
Es ist möglich, mehr als einen Submit-Button im Formular zu haben:
$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');
Um herauszufinden, welche von ihnen angeklickt wurde, verwenden Sie:
if ($form['register']->isSubmittedBy()) {
// ...
}
Wenn Sie das Formular nicht validieren wollen, wenn ein Submit-Button gedrückt wird (wie Abbrechen oder Vorschau), können Sie dies mit setValidationScope() ausschalten.
addButton(string|int $name, $caption): Button
Fügt eine Schaltfläche (Klasse Button) ohne Sendefunktion hinzu. Sie ist nützlich, um andere Funktionen an die id zu binden, zum Beispiel eine JavaScript-Aktion.
$form->addButton('raise', 'Raise salary')
->setHtmlAttribute('onclick', 'raiseSalary()');
addImageButton(string|int $name, string $src=null, string $alt=null): ImageButton
Fügt einen Submit-Button in Form eines Bildes hinzu (Klasse ImageButton).
$form->addImageButton('submit', '/path/to/image');
Wenn Sie mehrere Submit-Buttons verwenden, können Sie herausfinden, welcher Button angeklickt wurde mit
$form['submit']->isSubmittedBy()
.
addContainer(string|int $name): Container
Fügt ein Unterformular (Klasse Container) oder
einen Container hinzu, der genauso behandelt werden kann wie ein Formular. Das heißt, Sie können Methoden wie
setDefaults()
oder getValues()
verwenden.
$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:');
Die gesendeten Daten werden dann als multidimensionale Struktur zurückgegeben:
[
'first' => [
'name' => /* ... */,
'email' => /* ... */,
],
'second' => [
'name' => /* ... */,
'email' => /* ... */,
],
]
Übersicht der Einstellungen
Für alle Elemente können wir die folgenden Methoden aufrufen (siehe API-Dokumentation für eine vollständige Übersicht):
setDefaultValue($value) |
setzt den Standardwert |
getValue() |
liefert den aktuellen Wert |
setOmitted() |
Ausgelassene Werte |
setDisabled() |
Deaktivieren von Eingaben |
Rendering:
setCaption($caption) |
Ändern der Beschriftung des Eintrags |
setTranslator($translator) |
setzt den Übersetzer |
setHtmlAttribute($name, $value) |
setzt das HTML-Attribut des Elements |
setHtmlId($id) |
setzt das HTML-Attribut id |
setHtmlType($type) |
setzt HTML-Attribut type |
setHtmlName($name) |
setzt HTML-Attribut name |
setOption($key, $value) |
legt Rendering-Datenfest |
Validierung:
setRequired() |
Pflichtfeld |
addRule() |
Validierungsregel hinzufügen |
addCondition() , addConditionOn() |
Validierungsbedingung hinzufügen |
addError($message) |
Fehlermeldung übergeben |
Die folgenden Methoden können für die Elemente addText()
, addPassword()
,
addTextArea()
, addEmail()
, addInteger()
aufgerufen werden:
setNullable() |
legt fest, ob getValue() null statt eines leeren Strings zurückgibt |
setEmptyValue($value) |
legt den speziellen Wert fest, der als leerer String behandelt wird |
setMaxLength($length) |
legt die maximale Anzahl der erlaubten Zeichen fest |
addFilter($filter) |
Ändern von Eingabewerten |
Ausgelassene Werte
Wenn Sie an dem vom Benutzer eingegebenen Wert nicht interessiert sind, können wir setOmitted()
verwenden, um ihn
aus dem Ergebnis auszulassen, das von der Methode $form->getValues()
geliefert oder an Handler übergeben wird.
Dies eignet sich für verschiedene Passwörter zur Überprüfung, Antispam-Felder usw.
$form->addPassword('passwordVerify', 'Password again:')
->setRequired('Fill your password again to check for typo')
->addRule($form::Equal, 'Password mismatch', $form['password'])
->setOmitted();
Deaktivieren von Eingaben
Um eine Eingabe zu deaktivieren, können Sie setDisabled()
aufrufen. Ein solches Feld kann vom Benutzer nicht
bearbeitet werden.
$form->addText('username', 'User name:')
->setDisabled();
Beachten Sie, dass der Browser die deaktivierten Felder gar nicht an den Server sendet, so dass Sie sie nicht einmal in den von
der Funktion $form->getValues()
zurückgegebenen Daten finden werden.
Wenn Sie einen Standardwert für ein Feld festlegen, dürfen Sie dies erst tun, nachdem Sie das Feld deaktiviert haben:
$form->addText('username', 'User name:')
->setDisabled()
->setDefaultValue($userName);
Benutzerdefinierte Steuerelemente
Neben der großen Auswahl an eingebauten Steuerelementen können Sie dem Formular wie folgt benutzerdefinierte Steuerelemente hinzufügen:
$form->addComponent(new DateInput('Date:'), 'date');
// alternative Syntax: $form['date'] = new DateInput('Datum:');
Das Formular ist ein Abkömmling der Klasse Container und die Elemente sind Abkömmlinge von Component.
Es gibt eine Möglichkeit, neue Formularmethoden zu definieren, um benutzerdefinierte Elemente hinzuzufügen (z. B.
$form->addZip()
). Dies sind die sogenannten Erweiterungsmethoden. Der Nachteil ist, dass Codehinweise in Editoren
für sie nicht funktionieren.
use Nette\Forms\Container;
// fügt Methode 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, 'Mindestens 5 Zahlen', '[0-9]{5}');
});
// Verwendung
$form->addZip('zip', 'Postleitzahl:');
Low-Level-Felder
Um ein Element zum Formular hinzuzufügen, müssen Sie nicht $form->addXyz()
aufrufen. Formularelemente können
stattdessen ausschließlich in Vorlagen eingeführt werden. Dies ist nützlich, wenn Sie z. B. dynamische Elemente erzeugen
müssen:
{foreach $items as $item}
<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}
Nach dem Absenden können Sie die Werte abrufen:
$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');
Im ersten Parameter geben Sie den Elementtyp an (DataFile
für type=file
, DataLine
für
einzeilige Eingaben wie text
, password
oder email
und DataText
für die
übrigen). Der zweite Parameter entspricht dem HTML-Attribut name
. Wenn Sie Schlüssel beibehalten müssen, können
Sie den ersten Parameter mit DataKeys
kombinieren. Dies ist nützlich für select
,
radioList
oder checkboxList
.
getHttpData()
gibt die bereinigte Eingabe zurück. In diesem Fall handelt es sich immer um ein Array gültiger
UTF-8-Strings, unabhängig davon, was der Angreifer über das Formular gesendet hat. Es ist eine Alternative zur direkten Arbeit
mit $_POST
oder $_GET
, wenn Sie sichere Daten erhalten möchten.