Nette Documentation Preview

syntax 
Formular-Steuerelemente
***********************

.[perex]
Übersicht über die eingebauten Formularsteuerelemente.


addText(string|int $name, $label=null, $cols, ?int $maxLength=null): TextInput .[method]
========================================================================================

Fügt ein einzeiliges Textfeld hinzu (Klasse [TextInput |api:Nette\Forms\Controls\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.

```php
$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() |validation#Modifying Input Values] können Sie den vom Benutzer eingegebenen Wert ändern.

Sie können das visuelle Zeichen eines Textfeldes in Typen wie `search`, `tel` oder `url` ändern, indem Sie `setHtmlType()` verwenden, wie in der [Spezifikation |https://developer.mozilla.org/en-US/docs/Learn/Forms/HTML5_input_types] angegeben. Denken Sie daran, dass die Änderung des Typs nur visuell ist und keine Validierungsfunktionen ausführt. Für den Typ `url` ist es sinnvoll, eine spezielle [URL-Regel |validation#Text inputs] hinzuzufügen.

.[note]
Für andere Eingabetypen wie `number`, `range`, `email`, `date`, `datetime-local`, `time` und `color` verwenden Sie spezielle Methoden wie [addInteger |#addInteger], [addFloat |#addFloat], [addEmail |#addEmail] [addDate |#addDate], [addTime |#addTime], [addDateTime |#addDateTime] und [addColor |#addColor], die eine serverseitige Validierung gewährleisten. Die Typen `month` und `week` werden noch nicht von allen Browsern vollständig unterstützt.

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.

```php
$form->addText('phone', 'Phone:')
	->setHtmlType('tel')
	->setEmptyValue('+420');
```


addTextArea(string|int $name, $label=null): TextArea .[method]
==============================================================

Fügt ein mehrzeiliges Textfeld (Klasse [TextArea |api:Nette\Forms\Controls\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.

```php
$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() |validation#Modifying Input Values] 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 .[method]
==============================================================

Fügt Eingabefeld für Ganzzahl (Klasse [TextInput |api:Nette\Forms\Controls\TextInput]) hinzu. Gibt entweder eine Ganzzahl oder `null` zurück, wenn der Benutzer nichts eingibt.

```php
$form->addInteger('Jahr', 'Jahr:')
	->addRule($form::Range, 'Das Jahr muss im Bereich %d bis %d liegen.', [1900, 2023 |1900, 2023]);
```

Das Element wird wiedergegeben als `<input type="numeric">`. Mit der Methode `setHtmlType()` können Sie den Typ in `range` für die Anzeige als Schieberegler oder in `text` ändern, wenn Sie ein Standardtextfeld ohne das spezielle Verhalten von `numeric` bevorzugen.


addFloat(string|int $name, $label=null): TextInput .[method]{data-version:3.1.12}
=================================================================================

Adds a field for entering a decimal number ([TextInput |api:Nette\Forms\Controls\TextInput] class). Returns either float or `null`, if the user does not specify anything.

```php
$form->addFloat('Ebene', 'Ebene:')
	->setDefaultValue(0)
->addRule($form::Range, 'Das Niveau muss im Bereich %d bis %d liegen.', [0, 100 |0, 100]);
```

Das Element wird wiedergegeben als `<input type="numeric">`. Mit der Methode `setHtmlType()` können Sie den Typ in `range` für die Anzeige als Schieberegler oder in `text` ändern, wenn Sie ein Standardtextfeld ohne das spezielle Verhalten von `numeric` bevorzugen.

Nette und der Chrome-Browser akzeptieren sowohl ein Komma als auch einen Punkt als Dezimaltrennzeichen. Um diese Funktionalität in Firefox verfügbar zu machen, empfiehlt es sich, das Attribut `lang` entweder für das spezifische Element oder für die gesamte Seite zu setzen, zum Beispiel, `<html lang="cs">`.


addEmail(string|int $name, $label=null, int $maxLength=255): TextInput .[method]
================================================================================

Fügt ein E-Mail-Adressfeld mit Gültigkeitsprüfung hinzu (Klasse [TextInput |api:Nette\Forms\Controls\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.

```php
$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() |validation#Modifying Input Values] können Sie den vom Benutzer eingegebenen Wert ändern. Mit `setEmptyValue()` können Sie den sogenannten Leerwert setzen.


addPassword(string|int $name, $label=null, $cols, ?int $maxLength=null): TextInput .[method]
============================================================================================

Fügt Passwortfeld hinzu (Klasse [TextInput |api:Nette\Forms\Controls\TextInput]).

```php
$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 .[method]
================================================================

Fügt ein Kontrollkästchen (Klasse [Checkbox |api:Nette\Forms\Controls\Checkbox]) hinzu. Das Feld gibt entweder `true` oder `false` zurück, je nachdem, ob es markiert ist.

```php
$form->addCheckbox('agree', 'I agree with terms')
	->setRequired('You must agree with our terms');
```


addCheckboxList(string|int $name, $label=null, ?array $items=null): CheckboxList .[method]
==========================================================================================

Fügt eine Liste von Kontrollkästchen zur Auswahl mehrerer Elemente hinzu (Klasse [CheckboxList |api:Nette\Forms\Controls\CheckboxList]). Gibt das Array der Schlüssel der ausgewählten Elemente zurück. Die Methode `getSelectedItems()` gibt Werte anstelle von Schlüsseln zurück.

```php
$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.

Wenn Sie ein Formular mit der Methode `GET` absenden, können Sie eine kompaktere Datenübertragungsmethode wählen, die die Größe des Abfrage-Strings einspart. Dies wird durch die Einstellung des HTML-Attributs des Formulars aktiviert:

```php
$form->setHtmlAttribute('data-nette-compact');
```


addRadioList(string|int $name, $label=null, ?array $items=null): RadioList .[method]
====================================================================================

Fügt Optionsfelder hinzu (Klasse [RadioList |api:Nette\Forms\Controls\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.

```php
$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, ?int $size=null): SelectBox .[method]
==================================================================================================

Fügt ein Auswahlfeld hinzu (Klasse [SelectBox |api:Nette\Forms\Controls\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.

```php
$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:

```php
$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.

```php
$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, ?int $size=null): MultiSelectBox .[method]
============================================================================================================

Fügt ein Auswahlfeld mit mehreren Auswahlmöglichkeiten hinzu (Klasse [MultiSelectBox |api:Nette\Forms\Controls\MultiSelectBox]). Gibt das Array der Schlüssel der ausgewählten Elemente zurück. Die Methode `getSelectedItems()` gibt Werte anstelle von Schlüsseln zurück.

```php
$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 .[method]
=================================================================

Fügt ein Datei-Upload-Feld hinzu (Klasse [UploadControl |api:Nette\Forms\Controls\UploadControl]). Gibt das [FileUpload-Objekt |http:request#FileUpload] zurück, auch wenn der Benutzer keine Datei hochgeladen hat, was mit der Methode `FileUpload::hasFile()` herausgefunden werden kann.

```php
$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 |http:request#toImage].


addMultiUpload(string|int $name, $label=null): UploadControl .[method]
======================================================================

Fügt ein Feld zum Hochladen mehrerer Dateien hinzu (Klasse [UploadControl |api:Nette\Forms\Controls\UploadControl]). Gibt ein Array von Objekten [FileUpload |http:request#FileUpload] zurück. Die Methode `FileUpload::hasFile()` gibt `true` für jedes dieser Objekte zurück.

```php
$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 |http:request#toImage].


addDate(string|int $name, $label=null): DateTimeControl .[method]{data-version:3.1.14}
======================================================================================

Fügt ein Feld hinzu, das es dem Benutzer ermöglicht, auf einfache Weise ein Datum bestehend aus Jahr, Monat und Tag einzugeben (Klasse [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Für den Standardwert akzeptiert es entweder Objekte, die `DateTimeInterface` implementieren, eine Zeichenkette mit der Uhrzeit oder eine Zahl, die einen UNIX-Zeitstempel darstellt. Dasselbe gilt für die Regelargumente `Min`, `Max` oder `Range`, die das minimal und maximal zulässige Datum festlegen.

```php
$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));
```

Standardmäßig wird ein `DateTimeImmutable` Objekt zurückgegeben. Mit der Methode `setFormat()` können Sie ein [Textformat |https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] oder einen Zeitstempel angeben:

```php
$form->addDate('date', 'Date:')
	->setFormat('Y-m-d');
```


addTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl .[method]{data-version:3.1.14}
===============================================================================================================

Fügt ein Feld hinzu, das dem Benutzer die einfache Eingabe der Zeit in Stunden, Minuten und optional Sekunden ermöglicht (Klasse [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Als Standardwert akzeptiert es entweder Objekte, die `DateTimeInterface` implementieren, einen String mit der Zeit oder eine Zahl, die einen UNIX-Zeitstempel darstellt. Es wird nur die Zeitinformation aus diesen Eingaben verwendet; das Datum wird ignoriert. Dasselbe gilt für die Regelargumente `Min`, `Max` oder `Range`, die die minimal und maximal zulässige Zeit festlegen. Wenn der Mindestwert höher ist als der Höchstwert, wird ein Zeitbereich bis Mitternacht erstellt.

```php
$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);
```

Standardmäßig wird ein Objekt `DateTimeImmutable` (mit dem Datum des 1. Januar, Jahr 1) zurückgegeben. Mit der Methode `setFormat()` können Sie ein [Textformat |https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] angeben:

```php
$form->addTime('time', 'Time:')
	->setFormat('H:i');
```


addDateTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl .[method]{data-version:3.1.14}
===================================================================================================================

Fügt ein Feld hinzu, das es dem Benutzer ermöglicht, auf einfache Weise sowohl Datum als auch Uhrzeit einzugeben, bestehend aus Jahr, Monat, Tag, Stunden, Minuten und optional Sekunden (Klasse [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Als Standardwert akzeptiert es entweder Objekte, die `DateTimeInterface` implementieren, einen String mit der Zeit oder eine Zahl, die einen UNIX-Zeitstempel darstellt. Dasselbe gilt für die Regelargumente `Min`, `Max` oder `Range`, die das minimal und maximal zulässige Datum festlegen.

```php
$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'));
```

Standardmäßig wird ein `DateTimeImmutable` Objekt zurückgegeben. Mit der Methode `setFormat()` können Sie ein [Textformat |https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] oder einen Zeitstempel angeben:

```php
$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);
```


addColor(string|int $name, $label=null): ColorPicker .[method]{data-version:3.1.14}
===================================================================================

Fügt ein Farbauswahlfeld (Klasse [ColorPicker |api:Nette\Forms\Controls\ColorPicker]) hinzu. Die Farbe ist ein String im Format `#rrggbb`. Wenn der Benutzer keine Auswahl trifft, wird als Standardfarbe Schwarz zurückgegeben `#000000`.

```php
$form->addColor('color', 'Color:')
	->setDefaultValue('#3C8ED7');
```


addHidden(string|int $name, ?string $default=null): HiddenField .[method]
=========================================================================

Fügt ein verstecktes Feld (Klasse [HiddenField |api:Nette\Forms\Controls\HiddenField]) hinzu.

```php
$form->addHidden('userid');
```

Verwenden Sie `setNullable()`, um die Rückgabe von `null` anstelle eines leeren Strings zu ändern. Mit [addFilter() |validation#Modifying Input Values] können Sie den übergebenen Wert ändern.

Obwohl das Element verborgen ist, ist es **wichtig zu wissen**, dass sein Wert immer noch von einem Angreifer geändert oder gefälscht werden kann. Überprüfen und validieren Sie immer alle empfangenen Werte auf der Serverseite gründlich, um Sicherheitsrisiken im Zusammenhang mit Datenmanipulationen zu vermeiden.


addSubmit(string|int $name, $caption=null): SubmitButton .[method]
==================================================================

Fügt die Schaltfläche Submit (Klasse [SubmitButton |api:Nette\Forms\Controls\SubmitButton]) hinzu.

```php
$form->addSubmit('submit', 'Register');
```

Es ist möglich, mehr als einen Submit-Button im Formular zu haben:

```php
$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');
```

Um herauszufinden, welche von ihnen angeklickt wurde, verwenden Sie:

```php
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() |validation#Disabling Validation] ausschalten.


addButton(string|int $name, $caption): Button .[method]
=======================================================

Fügt eine Schaltfläche (Klasse [Button |api:Nette\Forms\Controls\Button]) ohne Sendefunktion hinzu. Sie ist nützlich, um andere Funktionen an die id zu binden, zum Beispiel eine JavaScript-Aktion.

```php
$form->addButton('raise', 'Raise salary')
	->setHtmlAttribute('onclick', 'raiseSalary()');
```


addImageButton(string|int $name, ?string $src=null, ?string $alt=null): ImageButton .[method]
=============================================================================================

Fügt einen Submit-Button in Form eines Bildes hinzu (Klasse [ImageButton |api:Nette\Forms\Controls\ImageButton]).

```php
$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 .[method]
===================================================

Fügt ein Unterformular (Klasse [Container |api:Nette\Forms\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.

```php
$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:

```php
[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]
```


Übersicht der Einstellungen .[#toc-overview-of-settings]
========================================================

Für alle Elemente können wir die folgenden Methoden aufrufen (siehe [API-Dokumentation |https://api.nette.org/forms/master/Nette/Forms/Controls.html] für eine vollständige Übersicht):

.[table-form-methods language-php]
| `setDefaultValue($value)` | setzt den Standardwert
| `getValue()` | liefert den aktuellen Wert
| `setOmitted()` | [Ausgelassene Werte |#omitted values]
| `setDisabled()` | [Deaktivieren von Eingaben |#disabling inputs]

Rendering:
.[table-form-methods language-php]
| `setCaption($caption)`| Ändern der Beschriftung des Eintrags
| `setTranslator($translator)` | setzt den [Übersetzer |rendering#translating]
| `setHtmlAttribute($name, $value)` | setzt das [HTML-Attribut |rendering#HTML attributes] 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 |rendering#Options]

Validierung:
.[table-form-methods language-php]
| `setRequired()` | [Pflichtfeld |validation]
| `addRule()` | [Validierungsregel hinzufügen |validation#Rules]
| `addCondition()`, `addConditionOn()` | [Validierungsbedingung hinzufügen |validation#Conditions]
| `addError($message)`| [Fehlermeldung übergeben |validation#processing-errors]

Die folgenden Methoden können für die Elemente `addText()`, `addPassword()`, `addTextArea()`, `addEmail()`, `addInteger()` aufgerufen werden:

.[table-form-methods language-php]
| `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 |validation#Modifying Input Values]


Ausgelassene Werte .[#toc-omitted-values]
=========================================

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.

```php
$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 .[#toc-disabling-inputs]
==================================================

Eingänge können mit `setDisabled()` deaktiviert werden. Ein deaktivierter Eingang kann vom Benutzer nicht bearbeitet werden.

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

Deaktivierte Eingaben werden vom Browser nicht an den Server gesendet, so dass sie in den von der Funktion `$form->getValues()` zurückgegebenen Daten nicht zu finden sind. Wenn Sie jedoch `setOmitted(false)` einstellen, wird Nette den Standardwert in diese Daten aufnehmen.

Wenn `setDisabled()` aufgerufen wird, wird **der Wert der Eingabe aus Sicherheitsgründen gelöscht**. Wenn Sie einen Standardwert setzen, müssen Sie dies nach seiner Deaktivierung tun:

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

Eine Alternative zu deaktivierten Eingaben sind Felder mit dem HTML-Attribut `readonly`, die vom Browser an den Server gesendet werden. Obwohl das Feld nur lesbar ist, ist es **wichtig zu wissen**, dass sein Wert trotzdem von einem Angreifer geändert oder gefälscht werden kann.


Benutzerdefinierte Steuerelemente .[#toc-custom-controls]
=========================================================

Neben der großen Auswahl an eingebauten Steuerelementen können Sie dem Formular wie folgt benutzerdefinierte Steuerelemente hinzufügen:

```php
$form->addComponent(new DateInput('Date:'), 'date');
// alternative Syntax: $form['date'] = new DateInput('Datum:');
```

.[note]
Das Formular ist ein Abkömmling der Klasse [Container | component-model:#Container] und die Elemente sind Abkömmlinge von [Component | component-model:#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.

```php
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 .[#toc-low-level-fields]
=========================================

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:

```latte
{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:

```php
$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.

Formular-Steuerelemente

Übersicht über die eingebauten Formularsteuerelemente.

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

Sie können das visuelle Zeichen eines Textfeldes in Typen wie search, tel oder url ändern, indem Sie setHtmlType() verwenden, wie in der Spezifikation angegeben. Denken Sie daran, dass die Änderung des Typs nur visuell ist und keine Validierungsfunktionen ausführt. Für den Typ url ist es sinnvoll, eine spezielle URL-Regel hinzuzufügen.

Für andere Eingabetypen wie number, range, email, date, datetime-local, time und color verwenden Sie spezielle Methoden wie addInteger, addFloat, addEmail addDate, addTime, addDateTime und addColor, die eine serverseitige Validierung gewährleisten. Die Typen month und week werden noch nicht von allen Browsern vollständig unterstützt.

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('Jahr', 'Jahr:')
	->addRule($form::Range, 'Das Jahr muss im Bereich %d bis %d liegen.', [1900, 2023 |1900, 2023]);

Das Element wird wiedergegeben als <input type="numeric">. Mit der Methode setHtmlType() können Sie den Typ in range für die Anzeige als Schieberegler oder in text ändern, wenn Sie ein Standardtextfeld ohne das spezielle Verhalten von numeric bevorzugen.

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('Ebene', 'Ebene:')
	->setDefaultValue(0)
->addRule($form::Range, 'Das Niveau muss im Bereich %d bis %d liegen.', [0, 100 |0, 100]);

Das Element wird wiedergegeben als <input type="numeric">. Mit der Methode setHtmlType() können Sie den Typ in range für die Anzeige als Schieberegler oder in text ändern, wenn Sie ein Standardtextfeld ohne das spezielle Verhalten von numeric bevorzugen.

Nette und der Chrome-Browser akzeptieren sowohl ein Komma als auch einen Punkt als Dezimaltrennzeichen. Um diese Funktionalität in Firefox verfügbar zu machen, empfiehlt es sich, das Attribut lang entweder für das spezifische Element oder für die gesamte Seite zu setzen, zum Beispiel, <html lang="cs">.

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

Wenn Sie ein Formular mit der Methode GET absenden, können Sie eine kompaktere Datenübertragungsmethode wählen, die die Größe des Abfrage-Strings einspart. Dies wird durch die Einstellung des HTML-Attributs des Formulars aktiviert:

$form->setHtmlAttribute('data-nette-compact');

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, ?int $size=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, ?int $size=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.

addDate(string|int $name, $label=null): DateTimeControl

Fügt ein Feld hinzu, das es dem Benutzer ermöglicht, auf einfache Weise ein Datum bestehend aus Jahr, Monat und Tag einzugeben (Klasse DateTimeControl).

Für den Standardwert akzeptiert es entweder Objekte, die DateTimeInterface implementieren, eine Zeichenkette mit der Uhrzeit oder eine Zahl, die einen UNIX-Zeitstempel darstellt. Dasselbe gilt für die Regelargumente Min, Max oder Range, die das minimal und maximal zulässige Datum festlegen.

$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Standardmäßig wird ein DateTimeImmutable Objekt zurückgegeben. Mit der Methode setFormat() können Sie ein Textformat oder einen Zeitstempel angeben:

$form->addDate('date', 'Date:')
	->setFormat('Y-m-d');

addTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Fügt ein Feld hinzu, das dem Benutzer die einfache Eingabe der Zeit in Stunden, Minuten und optional Sekunden ermöglicht (Klasse DateTimeControl).

Als Standardwert akzeptiert es entweder Objekte, die DateTimeInterface implementieren, einen String mit der Zeit oder eine Zahl, die einen UNIX-Zeitstempel darstellt. Es wird nur die Zeitinformation aus diesen Eingaben verwendet; das Datum wird ignoriert. Dasselbe gilt für die Regelargumente Min, Max oder Range, die die minimal und maximal zulässige Zeit festlegen. Wenn der Mindestwert höher ist als der Höchstwert, wird ein Zeitbereich bis Mitternacht erstellt.

$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);

Standardmäßig wird ein Objekt DateTimeImmutable (mit dem Datum des 1. Januar, Jahr 1) zurückgegeben. Mit der Methode setFormat() können Sie ein Textformat angeben:

$form->addTime('time', 'Time:')
	->setFormat('H:i');

addDateTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Fügt ein Feld hinzu, das es dem Benutzer ermöglicht, auf einfache Weise sowohl Datum als auch Uhrzeit einzugeben, bestehend aus Jahr, Monat, Tag, Stunden, Minuten und optional Sekunden (Klasse DateTimeControl).

Als Standardwert akzeptiert es entweder Objekte, die DateTimeInterface implementieren, einen String mit der Zeit oder eine Zahl, die einen UNIX-Zeitstempel darstellt. Dasselbe gilt für die Regelargumente Min, Max oder Range, die das minimal und maximal zulässige Datum festlegen.

$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'));

Standardmäßig wird ein DateTimeImmutable Objekt zurückgegeben. Mit der Methode setFormat() können Sie ein Textformat oder einen Zeitstempel angeben:

$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);

addColor(string|int $name, $label=null): ColorPicker

Fügt ein Farbauswahlfeld (Klasse ColorPicker) hinzu. Die Farbe ist ein String im Format #rrggbb. Wenn der Benutzer keine Auswahl trifft, wird als Standardfarbe Schwarz zurückgegeben #000000.

$form->addColor('color', 'Color:')
	->setDefaultValue('#3C8ED7');

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.

Obwohl das Element verborgen ist, ist es wichtig zu wissen, dass sein Wert immer noch von einem Angreifer geändert oder gefälscht werden kann. Überprüfen und validieren Sie immer alle empfangenen Werte auf der Serverseite gründlich, um Sicherheitsrisiken im Zusammenhang mit Datenmanipulationen zu vermeiden.

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

Eingänge können mit setDisabled() deaktiviert werden. Ein deaktivierter Eingang kann vom Benutzer nicht bearbeitet werden.

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

Deaktivierte Eingaben werden vom Browser nicht an den Server gesendet, so dass sie in den von der Funktion $form->getValues() zurückgegebenen Daten nicht zu finden sind. Wenn Sie jedoch setOmitted(false) einstellen, wird Nette den Standardwert in diese Daten aufnehmen.

Wenn setDisabled() aufgerufen wird, wird der Wert der Eingabe aus Sicherheitsgründen gelöscht. Wenn Sie einen Standardwert setzen, müssen Sie dies nach seiner Deaktivierung tun:

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

Eine Alternative zu deaktivierten Eingaben sind Felder mit dem HTML-Attribut readonly, die vom Browser an den Server gesendet werden. Obwohl das Feld nur lesbar ist, ist es wichtig zu wissen, dass sein Wert trotzdem von einem Angreifer geändert oder gefälscht werden kann.

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.