Formularelemente
Übersicht über die standardmäßigen Formularelemente.
addText (string|int $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput
Fügt ein einzeiliges Texteingabefeld hinzu (Klasse TextInput). Wenn der Benutzer das Feld nicht
ausfüllt, gibt es eine leere Zeichenkette ''
zurück, oder mit setNullable()
kann festgelegt werden,
dass null
zurückgegeben wird.
$form->addText('name', 'Name:')
->setRequired()
->setNullable();
Validiert automatisch UTF-8, schneidet führende und nachfolgende Leerzeichen ab und entfernt Zeilenumbrüche, die ein Angreifer senden könnte.
Die maximale Länge kann mit setMaxLength()
begrenzt werden. Der vom Benutzer eingegebene Wert kann mit addFilter() geändert werden.
Mit setHtmlType()
kann der visuelle Charakter des Textfeldes auf Typen wie search
, tel
oder url
geändert werden, siehe Spezifikation. Beachten Sie, dass die
Typänderung nur visuell ist und keine Validierungsfunktion ersetzt. Für den Typ url
ist es ratsam, eine spezifische
Validierungsregel URL hinzuzufügen.
Für andere Eingabetypen wie number
, range
, email
, date
,
datetime-local
, time
und color
verwenden Sie spezialisierte Methoden wie addInteger, addFloat, addEmail addDate, addTime, addDateTime und addColor, die die serverseitige Validierung sicherstellen. Die Typen month
und
week
werden derzeit noch nicht in allen Browsern vollständig unterstützt.
Dem Element kann ein sogenannter Empty-Value zugewiesen werden, was so etwas wie ein Standardwert ist, aber wenn der Benutzer
ihn nicht ändert, gibt das Element eine leere Zeichenkette oder null
zurück.
$form->addText('phone', 'Telefon:')
->setHtmlType('tel')
->setEmptyValue('+49'); // Beispiel für DE
addTextArea (string|int $name, $label=null): TextArea
Fügt ein Feld zur Eingabe von mehrzeiligem Text hinzu (Klasse TextArea). Wenn der Benutzer das Feld nicht
ausfüllt, gibt es eine leere Zeichenkette ''
zurück, oder mit setNullable()
kann festgelegt werden,
dass null
zurückgegeben wird.
$form->addTextArea('note', 'Anmerkung:')
->addRule($form::MaxLength, 'Anmerkung ist zu lang', 10000);
Validiert automatisch UTF-8 und normalisiert Zeilentrenner auf \n
. Im Gegensatz zum einzeiligen Eingabefeld
erfolgt kein Abschneiden von Leerzeichen.
Die maximale Länge kann mit setMaxLength()
begrenzt werden. Der vom Benutzer eingegebene Wert kann mit addFilter() geändert werden. Mit
setEmptyValue()
kann ein sogenannter Empty-Value festgelegt werden.
addInteger (string|int $name, $label=null): TextInput
Fügt ein Feld zur Eingabe einer ganzen Zahl hinzu (Klasse TextInput). Gibt entweder einen Integer oder
null
zurück, wenn der Benutzer nichts eingibt.
$form->addInteger('year', 'Jahr:')
->addRule($form::Range, 'Das Jahr muss im Bereich von %d bis %d liegen.', [1900, 2023]);
Das Element wird als <input type="number">
gerendert. Mit der Methode setHtmlType()
kann der
Typ auf range
geändert werden, um eine Darstellung als Schieberegler zu erhalten, oder auf text
, wenn
Sie ein Standard-Textfeld ohne das spezielle Verhalten des Typs number
bevorzugen.
addFloat (string|int $name, $label=null): TextInput
Fügt ein Feld zur Eingabe einer Dezimalzahl hinzu (Klasse TextInput). Gibt entweder einen Float oder
null
zurück, wenn der Benutzer nichts eingibt.
$form->addFloat('level', 'Level:')
->setDefaultValue(0)
->addRule($form::Range, 'Das Level muss im Bereich von %d bis %d liegen.', [0, 100]);
Das Element wird als <input type="number">
gerendert. Mit der Methode setHtmlType()
kann der
Typ auf range
geändert werden, um eine Darstellung als Schieberegler zu erhalten, oder auf text
, wenn
Sie ein Standard-Textfeld ohne das spezielle Verhalten des Typs number
bevorzugen.
Nette und der Chrome-Browser akzeptieren sowohl Komma als auch Punkt als Dezimaltrennzeichen. Damit diese Funktionalität auch
in Firefox verfügbar ist, wird empfohlen, das Attribut lang
entweder für das betreffende Element oder für die
gesamte Seite zu setzen, beispielsweise <html lang="de">
.
addEmail (string|int $name, $label=null, int $maxLength=255): TextInput
Fügt ein Feld zur Eingabe einer E-Mail-Adresse hinzu (Klasse TextInput). Wenn der Benutzer das Feld nicht
ausfüllt, gibt es eine leere Zeichenkette ''
zurück, oder mit setNullable()
kann festgelegt werden,
dass null
zurückgegeben wird.
$form->addEmail('email', 'E-Mail:');
Überprüft, ob der Wert eine gültige E-Mail-Adresse ist. Es wird nicht überprüft, ob die Domain tatsächlich existiert, es wird nur die Syntax überprüft. Validiert automatisch UTF-8, schneidet führende und nachfolgende Leerzeichen ab.
Die maximale Länge kann mit setMaxLength()
begrenzt werden. Der vom Benutzer eingegebene Wert kann mit addFilter() geändert werden. Mit
setEmptyValue()
kann ein sogenannter Empty-Value festgelegt werden.
addPassword (string|int $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput
Fügt ein Feld zur Eingabe eines Passworts hinzu (Klasse TextInput).
$form->addPassword('password', 'Passwort:')
->setRequired()
->addRule($form::MinLength, 'Das Passwort muss mindestens %d Zeichen lang sein', 8)
->addRule($form::Pattern, 'Muss eine Ziffer enthalten', '.*[0-9].*');
Beim erneuten Anzeigen des Formulars ist das Feld leer. Validiert automatisch UTF-8, schneidet führende und nachfolgende Leerzeichen ab und entfernt Zeilenumbrüche, die ein Angreifer senden könnte.
addCheckbox (string|int $name, $caption=null): Checkbox
Fügt ein Kontrollkästchen hinzu (Klasse Checkbox). Gibt entweder true
oder
false
zurück, je nachdem, ob es aktiviert ist.
$form->addCheckbox('agree', 'Ich stimme den Bedingungen zu')
->setRequired('Sie müssen den Bedingungen zustimmen');
addCheckboxList (string|int $name, $label=null, ?array $items=null): CheckboxList
Fügt Kontrollkästchen zur Auswahl mehrerer Elemente hinzu (Klasse CheckboxList). Gibt ein Array der Schlüssel
der ausgewählten Elemente zurück. Die Methode getSelectedItems()
gibt die Werte anstelle der Schlüssel
zurück.
$form->addCheckboxList('colors', 'Farben:', [
'r' => 'rot',
'g' => 'grün',
'b' => 'blau',
]);
Das Array der angebotenen Elemente übergeben wir als dritten Parameter oder mit der Methode setItems()
.
Mit setDisabled(['r', 'g'])
können einzelne Elemente deaktiviert werden.
Das Element überprüft automatisch, dass keine Manipulation stattgefunden hat und dass die ausgewählten Elemente tatsächlich
zu den angebotenen gehören und nicht deaktiviert wurden. Mit der Methode getRawValue()
können die gesendeten
Elemente ohne diese wichtige Überprüfung abgerufen werden.
Bei der Einstellung der standardmäßig ausgewählten Elemente wird ebenfalls überprüft, ob es sich um angebotene Elemente
handelt, andernfalls wird eine Ausnahme ausgelöst. Diese Prüfung kann mit checkDefaultValue(false)
deaktiviert
werden.
Wenn Sie das Formular mit der Methode GET
senden, können Sie eine kompaktere Datenübertragungsmethode wählen,
die die Größe des Query-Strings spart. Sie wird durch Setzen des HTML-Attributs des Formulars aktiviert:
$form->setHtmlAttribute('data-nette-compact');
addRadioList (string|int $name, $label=null, ?array $items=null): RadioList
Fügt Optionsschaltflächen 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 den Wert anstelle des Schlüssels zurück.
$sex = [
'm' => 'männlich',
'f' => 'weiblich',
];
$form->addRadioList('gender', 'Geschlecht:', $sex);
Das Array der angebotenen Elemente übergeben wir als dritten Parameter oder mit der Methode setItems()
.
Mit setDisabled(['m', 'f'])
können einzelne Elemente deaktiviert werden.
Das Element überprüft automatisch, dass keine Manipulation stattgefunden hat und dass das ausgewählte Element tatsächlich
zu den angebotenen gehört und nicht deaktiviert wurde. Mit der Methode getRawValue()
kann das gesendete Element ohne
diese wichtige Überprüfung abgerufen werden.
Bei der Einstellung des standardmäßig ausgewählten Elements wird ebenfalls überprüft, ob es sich um ein angebotenes
Element handelt, andernfalls wird eine Ausnahme ausgelöst. Diese Prüfung kann mit checkDefaultValue(false)
deaktiviert werden.
addSelect (string|int $name, $label=null, ?array $items=null, ?int $size=null): SelectBox
Fügt eine Select-Box 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 den Wert anstelle des Schlüssels zurück.
$countries = [
'DE' => 'Deutschland',
'AT' => 'Österreich',
'CH' => 'Schweiz',
];
$form->addSelect('country', 'Land:', $countries)
->setDefaultValue('AT');
Das Array der angebotenen Elemente übergeben wir als dritten Parameter oder mit der Methode setItems()
. Die
Elemente können auch ein zweidimensionales Array sein (für <optgroup>
):
$countries = [
'Europa' => [
'DE' => 'Deutschland',
'AT' => 'Österreich',
'CH' => 'Schweiz',
],
'CA' => 'Kanada',
'US' => 'USA',
'?' => 'andere',
];
Bei Select-Boxen hat das erste Element oft eine besondere Bedeutung, es dient als Aufforderung zur Aktion. Zum Hinzufügen
eines solchen Elements dient die Methode setPrompt()
.
$form->addSelect('country', 'Land:', $countries)
->setPrompt('Wählen Sie ein Land');
Mit setDisabled(['DE', 'AT'])
können einzelne Elemente deaktiviert werden.
Das Element überprüft automatisch, dass keine Manipulation stattgefunden hat und dass das ausgewählte Element tatsächlich
zu den angebotenen gehört und nicht deaktiviert wurde. Mit der Methode getRawValue()
kann das gesendete Element ohne
diese wichtige Überprüfung abgerufen werden.
Bei der Einstellung des standardmäßig ausgewählten Elements wird ebenfalls überprüft, ob es sich um ein angebotenes
Element handelt, andernfalls wird eine Ausnahme ausgelöst. Diese Prüfung kann mit checkDefaultValue(false)
deaktiviert werden.
addMultiSelect (string|int $name, $label=null, ?array $items=null, ?int $size=null): MultiSelectBox
Fügt eine Select-Box zur Auswahl mehrerer Elemente hinzu (Klasse MultiSelectBox). Gibt ein Array der
Schlüssel der ausgewählten Elemente zurück. Die Methode getSelectedItems()
gibt die Werte anstelle der Schlüssel
zurück.
$form->addMultiSelect('countries', 'Länder:', $countries);
Das Array der angebotenen Elemente übergeben wir als dritten Parameter oder mit der Methode setItems()
. Die
Elemente können auch ein zweidimensionales Array sein (für <optgroup>
).
Mit setDisabled(['DE', 'AT'])
können einzelne Elemente deaktiviert werden.
Das Element überprüft automatisch, dass keine Manipulation stattgefunden hat und dass die ausgewählten Elemente tatsächlich
zu den angebotenen gehören und nicht deaktiviert wurden. Mit der Methode getRawValue()
können die gesendeten
Elemente ohne diese wichtige Überprüfung abgerufen werden.
Bei der Einstellung der standardmäßig ausgewählten Elemente wird ebenfalls überprüft, ob es sich um angebotene Elemente
handelt, andernfalls wird eine Ausnahme ausgelöst. Diese Prüfung kann mit checkDefaultValue(false)
deaktiviert
werden.
addUpload (string|int $name, $label=null): UploadControl
Fügt ein Feld zum Hochladen einer Datei hinzu (Klasse UploadControl). Gibt ein FileUpload-Objekt zurück, auch wenn der Benutzer keine Datei
gesendet hat, was mit der Methode FileUpload::hasFile()
überprüft werden kann.
$form->addUpload('avatar', 'Avatar:')
->addRule($form::Image, 'Avatar muss JPEG, PNG, GIF, WebP oder AVIF sein.')
->addRule($form::MaxFileSize, 'Maximale Größe ist 1 MB.', 1024 * 1024); // 1 MB in Bytes
Wenn die Datei nicht korrekt hochgeladen werden kann, wird das Formular nicht erfolgreich gesendet und ein Fehler angezeigt.
D.h. bei erfolgreichem Senden muss die Methode FileUpload::isOk()
nicht überprüft werden.
Vertrauen Sie niemals dem ursprünglichen Dateinamen, der von der Methode FileUpload::getName()
zurückgegeben
wird, der Client könnte einen schädlichen Dateinamen gesendet haben, um Ihre Anwendung zu beschädigen oder zu hacken.
Die Regeln MimeType
und Image
erkennen den erforderlichen Typ anhand der Dateisignatur und
überprüfen nicht die Integrität der Datei. Ob ein Bild beschädigt ist, kann beispielsweise durch den Versuch, es zu laden, festgestellt werden.
addMultiUpload (string|int $name, $label=null): UploadControl
Fügt ein Feld zum gleichzeitigen Hochladen mehrerer Dateien hinzu (Klasse UploadControl). Gibt ein Array von FileUpload-Objekten zurück. Die Methode
FileUpload::hasFile()
gibt bei jedem von ihnen true
zurück, wenn eine Datei hochgeladen wurde.
$form->addMultiUpload('files', 'Dateien:')
->addRule($form::MaxLength, 'Maximal können %d Dateien hochgeladen werden', 10);
Wenn eine der Dateien nicht korrekt hochgeladen werden kann, wird das Formular nicht erfolgreich gesendet und ein Fehler
angezeigt. D.h. bei erfolgreichem Senden muss die Methode FileUpload::isOk()
nicht für jede Datei überprüft
werden, da das Formular als Ganzes ungültig wäre.
Vertrauen Sie niemals den ursprünglichen Dateinamen, die von der Methode FileUpload::getName()
zurückgegeben
werden, der Client könnte schädliche Dateinamen gesendet haben, um Ihre Anwendung zu beschädigen oder zu hacken.
Die Regeln MimeType
und Image
erkennen den erforderlichen Typ anhand der Dateisignatur und
überprüfen nicht die Integrität der Datei. Ob ein Bild beschädigt ist, kann beispielsweise durch den Versuch, es zu laden, festgestellt werden.
addDate (string|int $name, $label=null): DateTimeControl
Fügt ein Feld hinzu, das es dem Benutzer ermöglicht, einfach ein Datum bestehend aus Jahr, Monat und Tag einzugeben (Klasse DateTimeControl).
Als Standardwert akzeptiert es entweder Objekte, die die Schnittstelle DateTimeInterface
implementieren, eine
Zeichenkette mit der Zeit oder eine Zahl, die einen UNIX-Zeitstempel darstellt. Dasselbe gilt für die Argumente der Regeln
Min
, Max
oder Range
, die das minimal und maximal zulässige Datum definieren.
$form->addDate('date', 'Datum:')
->setDefaultValue(new DateTime)
->addRule($form::Min, 'Das Datum muss mindestens einen Monat alt sein.', new DateTime('-1 month'));
Standardmäßig gibt es ein DateTimeImmutable
-Objekt zurück, mit der Methode setFormat()
können Sie
das Textformat oder den
Zeitstempel angeben:
$form->addDate('date', 'Datum:')
->setFormat('Y-m-d');
addTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl
Fügt ein Feld hinzu, das es dem Benutzer ermöglicht, einfach eine Zeit bestehend aus Stunden, Minuten und optional auch Sekunden einzugeben (Klasse DateTimeControl).
Als Standardwert akzeptiert es entweder Objekte, die die Schnittstelle DateTimeInterface
implementieren, eine
Zeichenkette mit der Zeit oder eine Zahl, die einen UNIX-Zeitstempel darstellt. Aus diesen Eingaben wird nur die Zeitinformation
verwendet, das Datum wird ignoriert. Dasselbe gilt für die Argumente der Regeln Min
, Max
oder
Range
, die die minimal und maximal zulässige Zeit definieren. Wenn der minimale Wert höher als der maximale ist,
wird ein Zeitbereich erstellt, der Mitternacht überschreitet.
$form->addTime('time', 'Zeit:', withSeconds: true)
->addRule($form::Range, 'Die Zeit muss im Bereich von %d bis %d liegen.', ['12:30', '13:30']);
Standardmäßig gibt es ein DateTimeImmutable
-Objekt zurück (mit dem Datum 1. Januar des Jahres 1), mit der
Methode setFormat()
können Sie das Textformat angeben:
$form->addTime('time', 'Zeit:')
->setFormat('H:i');
addDateTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl
Fügt ein Feld hinzu, das es dem Benutzer ermöglicht, einfach Datum und Uhrzeit bestehend aus Jahr, Monat, Tag, Stunden, Minuten und optional auch Sekunden einzugeben (Klasse DateTimeControl).
Als Standardwert akzeptiert es entweder Objekte, die die Schnittstelle DateTimeInterface
implementieren, eine
Zeichenkette mit der Zeit oder eine Zahl, die einen UNIX-Zeitstempel darstellt. Dasselbe gilt für die Argumente der Regeln
Min
, Max
oder Range
, die das minimal und maximal zulässige Datum und die Uhrzeit
definieren.
$form->addDateTime('datetime', 'Datum und Uhrzeit:')
->setDefaultValue(new DateTime)
->addRule($form::Min, 'Das Datum muss mindestens einen Monat alt sein.', new DateTime('-1 month'));
Standardmäßig gibt es ein DateTimeImmutable
-Objekt zurück, mit der Methode setFormat()
können Sie
das Textformat oder den
Zeitstempel angeben:
$form->addDateTime('datetime')
->setFormat(DateTimeControl::FormatTimestamp);
addColor (string|int $name, $label=null): ColorPicker
Fügt ein Feld zur Farbauswahl hinzu (Klasse ColorPicker). Die Farbe ist eine Zeichenkette
im Format #rrggbb
. Wenn der Benutzer keine Auswahl trifft, wird die schwarze Farbe #000000
zurückgegeben.
$form->addColor('color', 'Farbe:')
->setDefaultValue('#3C8ED7');
addHidden (string|int $name, ?string $default=null): HiddenField
Fügt ein verstecktes Feld hinzu (Klasse HiddenField).
$form->addHidden('userid');
Mit setNullable()
kann festgelegt werden, dass null
anstelle einer leeren Zeichenkette zurückgegeben
wird. Der gesendete Wert kann mit addFilter()
geändert werden.
Obwohl das Element versteckt ist, ist es wichtig zu beachten, dass der Wert immer noch von einem Angreifer geändert oder gefälscht werden kann. Überprüfen und validieren Sie immer gründlich alle empfangenen Werte auf der Serverseite, um Sicherheitsrisiken im Zusammenhang mit Datenmanipulation zu vermeiden.
addSubmit (string|int $name, $caption=null): SubmitButton
Fügt eine Senden-Schaltfläche hinzu (Klasse SubmitButton).
$form->addSubmit('submit', 'Senden');
Es ist möglich, mehrere Senden-Schaltflächen in einem Formular zu haben:
$form->addSubmit('register', 'Registrieren');
$form->addSubmit('cancel', 'Abbrechen');
Um herauszufinden, welche davon geklickt wurde, verwenden Sie:
if ($form['register']->isSubmittedBy()) {
// ...
}
Wenn Sie das gesamte Formular beim Klicken auf eine Schaltfläche nicht validieren möchten (z. B. bei Schaltflächen Abbrechen oder Vorschau), verwenden Sie setValidationScope().
addButton (string|int $name, $caption): Button
Fügt eine Schaltfläche hinzu (Klasse Button), die keine Sende-Funktion hat. Sie kann also für eine andere Funktion verwendet werden, z. B. zum Aufrufen einer JavaScript-Funktion beim Klicken.
$form->addButton('raise', 'Gehalt erhöhen')
->setHtmlAttribute('onclick', 'raiseSalary()');
addImageButton (string|int $name, ?string $src=null, ?string $alt=null): ImageButton
Fügt eine Senden-Schaltfläche in Form eines Bildes hinzu (Klasse ImageButton).
$form->addImageButton('submit', '/pfad/zum/bild');
Bei Verwendung mehrerer Senden-Schaltflächen kann mit $form['submit']->isSubmittedBy()
ermittelt werden,
welche geklickt wurde.
addContainer (string|int $name): Container
Fügt ein Unterformular (Klasse Container), also
einen Container, hinzu, dem weitere Elemente auf die gleiche Weise hinzugefügt werden können, wie wir sie dem Formular
hinzufügen. Auch die Methoden setDefaults()
oder getValues()
funktionieren.
$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Ihr Name:');
$sub1->addEmail('email', 'E-Mail:');
$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Ihr Name:');
$sub2->addEmail('email', 'E-Mail:');
Die gesendeten Daten werden dann als mehrdimensionale Struktur zurückgegeben:
[
'first' => [
'name' => /* ... */,
'email' => /* ... */,
],
'second' => [
'name' => /* ... */,
'email' => /* ... */,
],
]
Übersicht der Einstellungen
Für alle Elemente können wir die folgenden Methoden aufrufen (vollständige Übersicht in der API-Dokumentation):
setDefaultValue($value) |
Setzt den Standardwert |
getValue() |
Ruft den aktuellen Wert ab |
setOmitted() |
Wert auslassen |
setDisabled() |
Elemente deaktivieren |
Rendering:
setCaption($caption) |
Ändert die Beschriftung des Elements |
setTranslator($translator) |
Setzt den Übersetzer |
setHtmlAttribute($name, $value) |
Setzt ein HTML-Attribut des Elements |
setHtmlId($id) |
Setzt das HTML-Attribut id |
setHtmlName($name) |
Setzt das HTML-Attribut name |
setHtmlType($type) |
Setzt das HTML-Attribut type |
setOption($key, $value) |
Einstellungen für das Rendering |
Validierung:
setRequired() |
Pflichtfeld |
addRule() |
Setzt eine Validierungsregel |
addCondition() , addConditionOn() |
Setzt eine Validierungsbedingung |
addError($message) |
Fehlermeldung übergeben |
Für die Elemente addText()
, addPassword()
, addTextArea()
, addEmail()
,
addInteger()
können die folgenden Methoden aufgerufen werden:
setNullable() |
Legt fest, ob getValue() null anstelle einer leeren Zeichenkette zurückgibt |
setEmptyValue($value) |
Setzt einen speziellen Wert, der als leere Zeichenkette betrachtet wird |
setMaxLength($length) |
Setzt die maximale Anzahl erlaubter Zeichen |
addFilter($filter) |
Eingabe anpassen |
Wert auslassen
Wenn uns der vom Benutzer ausgefüllte Wert nicht interessiert, können wir ihn mit setOmitted()
aus dem Ergebnis
der Methode $form->getValues()
oder aus den an die Handler übergebenen Daten auslassen. Dies ist nützlich für
verschiedene Kontrollpasswörter, Anti-Spam-Elemente usw.
$form->addPassword('passwordVerify', 'Passwort zur Kontrolle:')
->setRequired('Bitte geben Sie das Passwort zur Kontrolle noch einmal ein')
->addRule($form::Equal, 'Die Passwörter stimmen nicht überein', $form['password'])
->setOmitted();
Elemente deaktivieren
Elemente können mit setDisabled()
deaktiviert werden. Ein solches Element kann der Benutzer nicht bearbeiten.
$form->addText('username', 'Benutzername:')
->setDisabled();
Deaktivierte Elemente sendet der Browser überhaupt nicht an den Server, daher finden Sie sie auch nicht in den von der
Funktion $form->getValues()
zurückgegebenen Daten. Wenn Sie jedoch setOmitted(false)
einstellen,
schließt Nette ihren Standardwert in diese Daten ein.
Beim Aufruf von setDisabled()
wird aus Sicherheitsgründen der Wert des Elements gelöscht. Wenn Sie einen
Standardwert festlegen, muss dies nach der Deaktivierung erfolgen:
$form->addText('username', 'Benutzername:')
->setDisabled()
->setDefaultValue($userName);
Eine Alternative zu deaktivierten Elementen sind Elemente mit dem HTML-Attribut readonly
, die der Browser an den
Server sendet. Obwohl das Element nur lesbar ist, ist es wichtig zu beachten, dass sein Wert immer noch von einem Angreifer
geändert oder gefälscht werden kann.
Eigene Elemente
Neben der breiten Palette an integrierten Formularelementen können Sie dem Formular auf diese Weise eigene Elemente hinzufügen:
$form->addComponent(new DateInput('Datum:'), 'date');
// alternative Syntax: $form['date'] = new DateInput('Datum:');
Das Formular ist ein Nachkomme der Klasse Container und die einzelnen Elemente sind Nachkommen von Component.
Es gibt eine Möglichkeit, neue Methoden des Formulars zu definieren, die zum Hinzufügen eigener Elemente dienen (z. B.
$form->addZip()
). Dies sind sogenannte Extension Methods. Der Nachteil ist, dass die Code-Vervollständigung in
Editoren für sie nicht funktioniert.
use Nette\Forms\Container;
// wir fügen die Methode addZip(string $name, ?string $label = null) hinzu
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
return $form->addText($name, $label)
->addRule($form::Pattern, 'Mindestens 5 Ziffern', '[0-9]{5}');
});
// Verwendung
$form->addZip('zip', 'PLZ:');
Low-Level-Elemente
Es können auch Elemente verwendet werden, die wir nur im Template schreiben und nicht mit einer der
$form->addXyz()
-Methoden zum Formular hinzufügen. Wenn wir beispielsweise Datensätze aus der Datenbank ausgeben
und im Voraus nicht wissen, wie viele es sein werden und welche IDs sie haben werden, und wir bei jeder Zeile eine Checkbox oder
einen Radiobutton anzeigen möchten, reicht es aus, dies im Template zu codieren:
{foreach $items as $item}
<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}
Und nach dem Absenden ermitteln wir den Wert:
$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');
wobei der erste Parameter der Elementtyp ist (DataFile
für type=file
, DataLine
für
einzeilige Eingaben wie text
, password
, email
usw. und DataText
für alle
anderen wie checkbox
, radio
, textarea
) und der zweite Parameter sel[]
dem
HTML-Attribut name
entspricht. Den Elementtyp können wir mit dem Wert DataKeys
kombinieren, der die
Schlüssel der Elemente beibehält. Dies ist besonders nützlich für select
, radioList
und
checkboxList
.
Wichtig ist, dass getHttpData()
einen bereinigten Wert zurückgibt, in diesem Fall wird es immer ein Array
gültiger UTF-8-Zeichenketten sein, egal was ein Angreifer versuchen würde, dem Server unterzuschieben. Dies ist analog zur
direkten Arbeit mit $_POST
oder $_GET
, jedoch mit dem wesentlichen Unterschied, dass immer saubere Daten
zurückgegeben werden, so wie Sie es von den Standardelementen der Nette-Formulare gewohnt sind.