Nette Documentation Preview

syntax 
Formularelemente
****************

.[perex]
Übersicht der Standard-Formularelemente.


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

Fügt ein einzeiliges Textfeld hinzu (Klasse [TextInput |api:Nette\Forms\Controls\TextInput]). Füllt der Benutzer das Feld nicht aus, gibt es einen leeren String `''` zurück; mit `setNullable()` sorgen Sie dafür, dass es stattdessen `null` zurückgibt.

```php
$form->addText('name', 'Name:')
	->setRequired()
	->setNullable();
```

Es validiert automatisch UTF-8, schneidet Leerraum am Anfang und Ende ab und entfernt Zeilenumbrüche, die ein Angreifer senden könnte.

Die maximale Länge lässt sich mit `setMaxLength()` begrenzen. Die Methode [addFilter() |validation#Eingaben verändern] erlaubt es, den vom Benutzer eingegebenen Wert zu verändern.

Mit `setHtmlType()` können Sie das optische Erscheinungsbild des Textfelds auf Typen wie `search`, `tel` oder `url` ändern, wie sie die [Spezifikation|https://developer.mozilla.org/en-US/docs/Learn/Forms/HTML5_input_types] festlegt. Denken Sie daran, dass die Änderung des Typs rein optisch ist und die Validierung nicht ersetzt. Beim Typ `url` empfiehlt es sich, eine passende [Validierungsregel für URLs |validation#Texteingaben] zu ergänzen.

.[note]
Für andere Typen von Eingabefeldern wie `number`, `range`, `email`, `date`, `datetime-local`, `time` und `color` verwenden Sie die spezialisierten Methoden [#addInteger()], [#addFloat()], [#addEmail()], [#addDate()], [#addTime()], [#addDateTime()] und [#addColor()], die eine Validierung auf der Serverseite mitbringen. Die Typen `month` und `week` unterstützen noch nicht alle Browser vollständig.

Für das Element lässt sich ein "leerer Wert" setzen. Er verhält sich ein wenig wie ein Standardwert, aber wenn der Benutzer ihn nicht ändert, gibt das Element einen leeren String oder `null` zurück.

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


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

Fügt ein mehrzeiliges Textfeld hinzu (Klasse [TextArea |api:Nette\Forms\Controls\TextArea]). Füllt der Benutzer das Feld nicht aus, gibt es einen leeren String `''` zurück; mit `setNullable()` sorgen Sie dafür, dass es stattdessen `null` zurückgibt.

```php
$form->addTextArea('note', 'Notiz:')
	->addRule($form::MaxLength, 'Ihre Notiz ist viel zu lang', 10000);
```

Es validiert automatisch UTF-8 und vereinheitlicht die Zeilenenden zu `\n`. Anders als beim einzeiligen Feld wird kein Leerraum abgeschnitten.

Die maximale Länge lässt sich mit `setMaxLength()` begrenzen. Die Methode [addFilter() |validation#Eingaben verändern] erlaubt es, den vom Benutzer eingegebenen Wert zu verändern. Einen leeren Wert setzen Sie über `setEmptyValue()`.


addInteger(string $name, $label=null): TextInput .[method]
==========================================================

Fügt ein Feld zur Eingabe einer ganzen Zahl hinzu (Klasse [TextInput |api:Nette\Forms\Controls\TextInput]). Gibt entweder eine ganze Zahl zurück oder `null`, wenn der Benutzer nichts eingibt.

```php
$form->addInteger('year', 'Jahr:')
	->addRule($form::Range, 'Das Jahr muss zwischen %d und %d liegen.', [1900, 2023]);
```

Das Element wird als `<input type="number">` gerendert. Über die Methode `setHtmlType()` können Sie den Typ auf `range` ändern, um es als Schieberegler darzustellen, oder auf `text`, wenn Sie ein gewöhnliches Textfeld ohne das besondere Verhalten des Typs `number` vorziehen.


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

Fügt ein Feld zur Eingabe einer Fließkommazahl hinzu (Klasse [TextInput |api:Nette\Forms\Controls\TextInput]). Gibt entweder eine Fließkommazahl zurück oder `null`, wenn der Benutzer nichts eingibt.

```php
$form->addFloat('level', 'Stufe:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Die Stufe muss zwischen %d und %d liegen.', [0, 100]);
```

Das Element wird als `<input type="number">` gerendert. Über die Methode `setHtmlType()` können Sie den Typ auf `range` ändern, um es als Schieberegler darzustellen, oder auf `text`, wenn Sie ein gewöhnliches Textfeld ohne das besondere Verhalten des Typs `number` vorziehen.

Nette und der Browser Chrome akzeptieren als Dezimaltrennzeichen sowohl das Komma als auch den Punkt. Damit das auch in Firefox funktioniert, empfiehlt es sich, das Attribut `lang` entweder für das jeweilige Element oder für die ganze Seite zu setzen, zum Beispiel `<html lang="de">`.


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

Fügt ein Feld zur Eingabe einer E-Mail-Adresse hinzu (Klasse [TextInput |api:Nette\Forms\Controls\TextInput]). Füllt der Benutzer das Feld nicht aus, gibt es einen leeren String `''` zurück; mit `setNullable()` sorgen Sie dafür, dass es stattdessen `null` zurückgibt.

```php
$form->addEmail('email', 'E-Mail:');
```

Es prüft, ob der Wert eine gültige E-Mail-Adresse ist. Ob die Domain tatsächlich existiert, wird nicht geprüft, sondern nur die Syntax. Es validiert automatisch UTF-8 und schneidet Leerraum am Anfang und Ende ab.

Die maximale Länge lässt sich mit `setMaxLength()` begrenzen. Die Methode [addFilter() |validation#Eingaben verändern] erlaubt es, den vom Benutzer eingegebenen Wert zu verändern. Einen leeren Wert setzen Sie über `setEmptyValue()`.


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

Fügt ein Feld zur Eingabe eines Passworts hinzu (Klasse [TextInput |api:Nette\Forms\Controls\TextInput]).

```php
$form->addPassword('password', 'Passwort:')
	->setRequired()
	->addRule($form::MinLength, 'Das Passwort muss mindestens %d Zeichen lang sein', 8)
	->addRule($form::Pattern, 'Das Passwort muss eine Ziffer enthalten', '.*[0-9].*');
```

Wird das Formular erneut angezeigt, ist das Feld leer. Es validiert automatisch UTF-8, schneidet Leerraum am Anfang und Ende ab und entfernt Zeilenumbrüche, die ein Angreifer senden könnte.


addCheckbox(string $name, $caption=null): Checkbox .[method]
============================================================

Fügt eine Checkbox hinzu (Klasse [Checkbox |api:Nette\Forms\Controls\Checkbox]). Gibt `true` oder `false` zurück, je nachdem, ob sie angehakt ist.

```php
$form->addCheckbox('agree', 'Ich stimme den Bedingungen zu')
	->setRequired('Sie müssen unseren Bedingungen zustimmen');
```


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

Fügt eine Liste von Checkboxen zur Auswahl mehrerer Elemente hinzu (Klasse [CheckboxList |api:Nette\Forms\Controls\CheckboxList]). Gibt ein Array der Schlüssel der ausgewählten Elemente zurück. Die Methode `getSelectedItems()` gibt die ausgewählten Elemente als Schlüssel-Wert-Paare zurück.

```php
$form->addCheckboxList('colors', 'Farben:', [
	'r' => 'rot',
	'g' => 'grün',
	'b' => 'blau',
]);
```

Das Array der angebotenen Elemente übergeben Sie als dritten Parameter oder über die Methode `setItems()`. Übergeben Sie `setItems()` als zweites Argument `false`, werden die Werte zugleich als Schlüssel verwendet.

Mit `setDisabled(['r', 'g'])` deaktivieren Sie einzelne Elemente.

Das Element prüft automatisch, dass keine Fälschung stattgefunden hat und dass die ausgewählten Elemente tatsächlich zu den angebotenen gehören und nicht deaktiviert waren. Über die Methode `getRawValue()` lassen sich die gesendeten Elemente ohne diese wichtige Prüfung holen.

Beim Setzen der standardmäßig ausgewählten Elemente wird ebenfalls geprüft, dass sie zu den angebotenen gehören, sonst wirft es eine Exception. Diese Prüfung lässt sich mit `checkDefaultValue(false)` abschalten.

Wenn Sie das Formular mit der Methode `GET` absenden, können Sie eine kompaktere Art der Datenübertragung wählen, die Platz im Query-String spart. Sie aktivieren sie, indem Sie am Formular ein HTML-Attribut setzen:

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


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

Fügt Radiobuttons 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 statt des Schlüssels den Wert zurück.

```php
$sex = [
	'm' => 'männlich',
	'f' => 'weiblich',
	'o' => 'anderes',
];
$form->addRadioList('gender', 'Geschlecht:', $sex);
```

Das Array der angebotenen Elemente übergeben Sie als dritten Parameter oder über die Methode `setItems()`.

Mit `setDisabled(['m'])` deaktivieren Sie einzelne Elemente.

Das Element prüft automatisch, dass keine Fälschung stattgefunden hat und dass das ausgewählte Element tatsächlich zu den angebotenen gehört und nicht deaktiviert war. Über die Methode `getRawValue()` lässt sich das gesendete Element ohne diese wichtige Prüfung holen.

Beim Setzen des standardmäßig ausgewählten Elements wird ebenfalls geprüft, dass es zu den angebotenen gehört, sonst wirft es eine Exception. Diese Prüfung lässt sich mit `checkDefaultValue(false)` abschalten.


addSelect(string $name, $label=null, ?array $items=null, ?int $size=null): SelectBox .[method]
==============================================================================================

Fügt eine Select-Box 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 statt des Schlüssels den Wert zurück.

```php
$countries = [
	'CZ' => 'Tschechien',
	'SK' => 'Slowakei',
	'GB' => 'Großbritannien',
];

$form->addSelect('country', 'Land:', $countries)
	->setDefaultValue('SK');
```

Das Array der angebotenen Elemente übergeben Sie als dritten Parameter oder über die Methode `setItems()`. Die Elemente können auch ein zweidimensionales Array sein (das Optgroups darstellt):

```php
$countries = [
	'Europe' => [
		'CZ' => 'Tschechien',
		'SK' => 'Slowakei',
		'GB' => 'Großbritannien',
	],
	'CA' => 'Kanada',
	'US' => 'USA',
	'?'  => 'anderes',
];
```

In Select-Boxen hat das erste Element oft eine besondere Bedeutung und dient als Aufforderung zum Handeln. Über die Methode `setPrompt()` fügen Sie ein solches Element hinzu.

```php
$form->addSelect('country', 'Land:', $countries)
	->setPrompt('Wählen Sie ein Land');
```

Mit `setDisabled(['CZ', 'SK'])` deaktivieren Sie einzelne Elemente.

Das Element prüft automatisch, dass keine Fälschung stattgefunden hat und dass das ausgewählte Element tatsächlich zu den angebotenen gehört und nicht deaktiviert war. Über die Methode `getRawValue()` lässt sich das gesendete Element ohne diese wichtige Prüfung holen.

Beim Setzen des standardmäßig ausgewählten Elements wird ebenfalls geprüft, dass es zu den angebotenen gehört, sonst wirft es eine Exception. Diese Prüfung lässt sich mit `checkDefaultValue(false)` abschalten.


addMultiSelect(string $name, $label=null, ?array $items=null, ?int $size=null): MultiSelectBox .[method]
========================================================================================================

Fügt eine Select-Box zur Auswahl mehrerer Elemente hinzu (Klasse [MultiSelectBox |api:Nette\Forms\Controls\MultiSelectBox]). Gibt ein Array der Schlüssel der ausgewählten Elemente zurück. Die Methode `getSelectedItems()` gibt die ausgewählten Elemente als Schlüssel-Wert-Paare zurück.

```php
$form->addMultiSelect('countries', 'Länder:', $countries);
```

Das Array der angebotenen Elemente übergeben Sie als dritten Parameter oder über die Methode `setItems()`. Die Elemente können auch ein zweidimensionales Array sein.

Mit `setDisabled(['CZ', 'SK'])` deaktivieren Sie einzelne Elemente.

Das Element prüft automatisch, dass keine Fälschung stattgefunden hat und dass die ausgewählten Elemente tatsächlich zu den angebotenen gehören und nicht deaktiviert waren. Über die Methode `getRawValue()` lassen sich die gesendeten Elemente ohne diese wichtige Prüfung holen.

Beim Setzen der standardmäßig ausgewählten Elemente wird ebenfalls geprüft, dass sie zu den angebotenen gehören, sonst wirft es eine Exception. Diese Prüfung lässt sich mit `checkDefaultValue(false)` abschalten.


addUpload(string $name, $label=null): UploadControl .[method]
=============================================================

Fügt ein Feld zum Hochladen einer Datei hinzu (Klasse [UploadControl |api:Nette\Forms\Controls\UploadControl]). Gibt ein Objekt [FileUpload |http:request#FileUpload] zurück, auch wenn der Benutzer keine Datei hochgeladen hat, was sich über die Methode `FileUpload::hasFile()` prüfen lässt. Mit `setNullable()` sorgen Sie dafür, dass das Element `null` statt eines `FileUpload`-Objekts zurückgibt, wenn keine Datei hochgeladen wurde.

```php
$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Der Avatar muss JPEG, PNG, GIF, WebP oder AVIF sein.')
	->addRule($form::MaxFileSize, 'Die maximale Größe beträgt 1 MB.', 1024 * 1024);
```

Lässt sich die Datei nicht korrekt hochladen, wird das Formular nicht erfolgreich abgesendet und ein Fehler angezeigt. Nach erfolgreichem Absenden muss die Methode `FileUpload::isOk()` also nicht geprüft werden.

Vertrauen Sie niemals dem ursprünglichen Dateinamen, den die Methode `FileUpload::getName()` zurückgibt; der Client könnte einen bösartigen Dateinamen gesendet haben, um Ihre Anwendung zu beschädigen oder zu kapern.

Die Regeln `MimeType` und `Image` erkennen den verlangten Typ anhand der Signatur der Datei und prüfen ihre Unversehrtheit nicht. Ob ein Bild beschädigt ist, lässt sich zum Beispiel durch den Versuch feststellen, es zu [laden |http:request#toImage()].


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

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

```php
$form->addMultiUpload('files', 'Dateien:')
	->addRule($form::MaxLength, 'Es lassen sich höchstens %d Dateien hochladen.', 10);
```

Lässt sich eine der Dateien nicht korrekt hochladen, wird das Formular nicht erfolgreich abgesendet und ein Fehler angezeigt. Nach erfolgreichem Absenden muss die Methode `FileUpload::isOk()` also nicht für jede Datei geprüft werden.

Vertrauen Sie niemals den ursprünglichen Dateinamen, die die Methode `FileUpload::getName()` zurückgibt; der Client könnte bösartige Dateinamen gesendet haben, um Ihre Anwendung zu beschädigen oder zu kapern.

Die Regeln `MimeType` und `Image` erkennen den verlangten Typ anhand der Signatur der Datei und prüfen ihre Unversehrtheit nicht. Ob ein Bild beschädigt ist, lässt sich zum Beispiel durch den Versuch feststellen, es zu [laden |http:request#toImage()].


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

Fügt ein Feld hinzu, in dem der Benutzer bequem ein Datum aus Jahr, Monat und Tag eingeben kann (Klasse [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Als Standardwert akzeptiert es Objekte, die `DateTimeInterface` implementieren, einen String mit einer Zeitangabe oder eine Zahl, die einen UNIX-Timestamp darstellt. Dasselbe gilt für die Argumente der Regeln `Min`, `Max` und `Range`, die das früheste und späteste erlaubte Datum festlegen.

```php
$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. Über die Methode `setFormat()` können Sie ein [Textformat|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] oder einen Timestamp angeben:

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


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

Fügt ein Feld hinzu, in dem der Benutzer bequem eine Zeit aus Stunden, Minuten und wahlweise Sekunden eingeben kann (Klasse [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Als Standardwert akzeptiert es Objekte, die `DateTimeInterface` implementieren, einen String mit einer Zeitangabe oder eine Zahl, die einen UNIX-Timestamp darstellt. Aus diesen Eingaben wird nur die Zeitangabe verwendet, das Datum wird ignoriert. Dasselbe gilt für die Argumente der Regeln `Min`, `Max` und `Range`, die die früheste und späteste erlaubte Zeit festlegen. Ist der gesetzte Mindestwert höher als der Höchstwert, entsteht ein Zeitbereich über Mitternacht hinweg.

```php
$form->addTime('time', 'Zeit:', withSeconds: true)
	->addRule($form::Range, 'Die Zeit muss zwischen %d und %d liegen.', ['12:30', '13:30']);
```

Standardmäßig gibt es ein `DateTimeImmutable`-Objekt zurück (mit dem Datum 1. Januar des Jahres 1). Über die 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', 'Zeit:')
	->setFormat('H:i');
```


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

Fügt ein Feld hinzu, in dem der Benutzer bequem Datum und Zeit zugleich eingeben kann, also Jahr, Monat, Tag, Stunden, Minuten und wahlweise Sekunden (Klasse [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

Als Standardwert akzeptiert es Objekte, die `DateTimeInterface` implementieren, einen String mit einer Zeitangabe oder eine Zahl, die einen UNIX-Timestamp darstellt. Dasselbe gilt für die Argumente der Regeln `Min`, `Max` und `Range`, die das früheste und späteste erlaubte Datum samt Zeit festlegen.

```php
$form->addDateTime('datetime', 'Datum und Zeit:')
	->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. Über die Methode `setFormat()` können Sie ein [Textformat|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] oder einen Timestamp angeben:

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


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

Fügt ein Feld zur Auswahl einer Farbe hinzu (Klasse [ColorPicker |api:Nette\Forms\Controls\ColorPicker]). Die Farbe wird als String im Format `#rrggbb` zurückgegeben. Trifft der Benutzer keine Auswahl, gibt es Schwarz `#000000` zurück.

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


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

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

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

Mit `setNullable()` sorgen Sie dafür, dass es `null` statt eines leeren Strings zurückgibt. Die Methode [addFilter() |validation#Eingaben verändern] erlaubt es, den gesendeten Wert zu verändern.

Auch wenn das Element versteckt ist, **muss Ihnen klar sein**, dass sich sein Wert von einem Angreifer trotzdem verändern oder fälschen lässt. Prüfen und validieren Sie alle empfangenen Werte auf der Serverseite immer gründlich, um Sicherheitsrisiken durch Manipulation der Daten zu vermeiden.


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

Fügt einen Absende-Button hinzu (Klasse [SubmitButton |api:Nette\Forms\Controls\SubmitButton]).

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

.{data-version:3.3.0}
Den Handler können Sie dem Button als dritten Parameter `$onSubmit` direkt übergeben, statt ihn an das Event `onClick` zu hängen:

```php
$form->addSubmit('submit', 'Absenden', function (SubmitButton $button, $data): void {
	// ...
});
```

Ein Formular kann mehr als einen Absende-Button haben:

```php
$form->addSubmit('register', 'Registrieren');
$form->addSubmit('cancel', 'Abbrechen');
```

Um festzustellen, welcher davon gedrückt wurde, verwenden Sie:

```php
if ($form['register']->isSubmittedBy()) {
  // ...
}
```

Wenn Sie beim Drücken eines Buttons nicht das gesamte Formular validieren wollen (etwa bei den Buttons *Abbrechen* oder *Vorschau*), verwenden Sie [setValidationScope() |validation#Validierung abschalten].


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

Fügt einen Button hinzu (Klasse [Button |api:Nette\Forms\Controls\Button]), der keine Absendefunktion hat. Er lässt sich daher für andere Aufgaben nutzen, etwa um beim Klick eine JavaScript-Funktion aufzurufen.

```php
$form->addButton('raise', 'Gehalt erhöhen')
	->setHtmlAttribute('onclick', 'raiseSalary()');
```


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

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

```php
$form->addImageButton('submit', '/path/to/image.png', 'Absenden');
```

Verwenden Sie mehrere Absende-Buttons, stellen Sie über `$form['submit']->isSubmittedBy()` fest, welcher davon gedrückt wurde.


addContainer(string|int $name): Container .[method]
===================================================

Fügt ein Unterformular hinzu (Klasse [Container|api:Nette\Forms\Container]), also einen Container, dem sich weitere Elemente auf dieselbe Weise hinzufügen lassen wie dem Formular. Methoden wie `setDefaults()` oder `getValues()` funktionieren ebenfalls.

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

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


Übersicht der Einstellungen
===========================

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

.[table-form-methods language-php]
| `setDefaultValue($value)` | setzt den Standardwert
| `getValue()` 				| holt den aktuellen Wert
| `setOmitted()` 			| [#Ausgelassene Werte]
| `setDisabled()` 			| [#Elemente deaktivieren]

Rendering:
.[table-form-methods language-php]
| `setCaption($caption)`	| ändert das Label des Elements
| `setTranslator($translator)` | setzt den [Übersetzer |rendering#Übersetzen]
| `setHtmlAttribute($name, $value)` | setzt ein [HTML-Attribut |rendering#HTML-Attribute] des Elements
| `setHtmlId($id)` 			| setzt das HTML-Attribut `id`
| `setOption($key, $value)` | [setzt die Optionen für das Rendering |rendering#Options]

Validierung:
.[table-form-methods language-php]
| `setRequired()` 			| macht das Element zum [Pflichtfeld |validation]
| `addRule()` 				| fügt eine [Validierungsregel |validation#Regeln] hinzu
| `addCondition()`, `addConditionOn()` | setzt eine [Validierungsbedingung |validation#Bedingungen]
| `addError($message)`		| [fügt eine Fehlermeldung hinzu |validation#Fehler verarbeiten]

Für die Elemente `addText()`, `addPassword()`, `addTextArea()`, `addEmail()`, `addInteger()`, `addFloat()` lassen sich die folgenden Methoden aufrufen:

.[table-form-methods language-php]
| `setNullable()` 			| legt fest, ob getValue() statt eines leeren Strings `null` zurückgibt
| `setEmptyValue($value)`	| setzt einen besonderen Wert, der als leerer String gilt
| `setMaxLength($length)`	| setzt die maximal erlaubte Anzahl von Zeichen
| `addFilter($filter)`		| [verändert die Eingabe |validation#Eingaben verändern]


Ausgelassene Werte
==================

Wenn uns der vom Benutzer eingegebene Wert nicht interessiert, können wir ihn mit `setOmitted()` aus dem Ergebnis der Methode `$form->getValues()` und aus den Daten für die Handler ausschließen. Das ist bei Feldern zur Bestätigung eines Passworts, bei Anti-Spam-Elementen und Ähnlichem nützlich.

```php
$form->addPassword('passwordVerify', 'Passwort erneut:')
	->setRequired('Geben Sie das Passwort zur Kontrolle erneut ein')
	->addRule($form::Equal, 'Die Passwörter stimmen nicht überein', $form['password'])
	->setOmitted();
```


Elemente deaktivieren
=====================

Elemente lassen sich mit `setDisabled()` deaktivieren. Ein deaktiviertes Element kann der Benutzer nicht bearbeiten.

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

Deaktivierte Elemente sendet der Browser gar nicht erst an den Server, Sie finden sie also nicht in den Daten, die die Funktion `$form->getValues()` zurückgibt. Setzen Sie jedoch `setOmitted(false)`, nimmt Nette ihren Standardwert in diese Daten auf.

Beim Aufruf von `setDisabled()` wird der **Wert des Elements aus Sicherheitsgründen gelöscht**. Wenn Sie einen Standardwert setzen, müssen Sie das also nach dem Deaktivieren tun:

```php
$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. Auch wenn das Element nur lesbar ist, **muss Ihnen klar sein**, dass sich sein Wert von einem Angreifer trotzdem verändern oder fälschen lässt.


Eigene Elemente
===============

Neben der breiten Palette eingebauter Formularelemente können Sie dem Formular eigene Elemente hinzufügen:

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

Wie sich ein solches Element schreiben lässt, samt Einlesen der gesendeten Daten, Validierung und Rendering, beschreibt ein [eigenes Kapitel |custom-controls]. Dort erfahren Sie auch etwas über Extension-Methoden, mit denen Sie sich eine eigene Methode zum Hinzufügen wie `$form->addZip()` schreiben können.


Low-Level-Elemente
==================

Sie können auch Elemente verwenden, die nur im Template stehen und dem Formular über keine der Methoden `$form->addXyz()` hinzugefügt wurden. Wenn wir zum Beispiel Datensätze aus einer Datenbank auflisten und vorher nicht wissen, wie viele es sein werden und welche IDs sie haben, und für jede Zeile eine Checkbox oder einen Radiobutton anzeigen wollen, schreiben wir das einfach ins Template:

```latte
{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}
```

Und nach dem Absenden holen wir den Wert:

```php
$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');
```

Der erste Parameter ist dabei der Typ des Elements (`DataFile` für `type=file`, `DataLine` für einzeilige Eingaben wie `text`, `password`, `email` und so weiter, und `DataText` für alle übrigen), der zweite Parameter `sel[]` entspricht dem HTML-Attribut name. Den Typ des Elements können wir mit dem Wert `DataKeys` kombinieren, der die Schlüssel der Elemente erhält. Besonders nützlich ist das bei `select`, `radioList` und `checkboxList`.

Entscheidend ist, dass `getHttpData()` einen bereinigten Wert zurückgibt. In diesem Fall wird es immer ein Array gültiger UTF-8-Strings sein, ganz gleich, was ein Angreifer an den Server zu senden versucht. Das ist analog zur direkten Arbeit mit `$_POST` oder `$_GET`, mit dem wesentlichen Unterschied, dass es immer saubere Daten zurückgibt, so wie Sie es von den Standard-Formularelementen von Nette gewohnt sind.

Formularelemente

Übersicht der Standard-Formularelemente.

addText(string $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput

Fügt ein einzeiliges Textfeld hinzu (Klasse TextInput). Füllt der Benutzer das Feld nicht aus, gibt es einen leeren String '' zurück; mit setNullable() sorgen Sie dafür, dass es stattdessen null zurückgibt.

$form->addText('name', 'Name:')
	->setRequired()
	->setNullable();

Es validiert automatisch UTF-8, schneidet Leerraum am Anfang und Ende ab und entfernt Zeilenumbrüche, die ein Angreifer senden könnte.

Die maximale Länge lässt sich mit setMaxLength() begrenzen. Die Methode addFilter() erlaubt es, den vom Benutzer eingegebenen Wert zu verändern.

Mit setHtmlType() können Sie das optische Erscheinungsbild des Textfelds auf Typen wie search, tel oder url ändern, wie sie die Spezifikation festlegt. Denken Sie daran, dass die Änderung des Typs rein optisch ist und die Validierung nicht ersetzt. Beim Typ url empfiehlt es sich, eine passende Validierungsregel für URLs zu ergänzen.

Für andere Typen von Eingabefeldern wie number, range, email, date, datetime-local, time und color verwenden Sie die spezialisierten Methoden addInteger(), addFloat(), addEmail(), addDate(), addTime(), addDateTime() und addColor(), die eine Validierung auf der Serverseite mitbringen. Die Typen month und week unterstützen noch nicht alle Browser vollständig.

Für das Element lässt sich ein „leerer Wert“ setzen. Er verhält sich ein wenig wie ein Standardwert, aber wenn der Benutzer ihn nicht ändert, gibt das Element einen leeren String oder null zurück.

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

addTextArea(string $name, $label=null): TextArea

Fügt ein mehrzeiliges Textfeld hinzu (Klasse TextArea). Füllt der Benutzer das Feld nicht aus, gibt es einen leeren String '' zurück; mit setNullable() sorgen Sie dafür, dass es stattdessen null zurückgibt.

$form->addTextArea('note', 'Notiz:')
	->addRule($form::MaxLength, 'Ihre Notiz ist viel zu lang', 10000);

Es validiert automatisch UTF-8 und vereinheitlicht die Zeilenenden zu \n. Anders als beim einzeiligen Feld wird kein Leerraum abgeschnitten.

Die maximale Länge lässt sich mit setMaxLength() begrenzen. Die Methode addFilter() erlaubt es, den vom Benutzer eingegebenen Wert zu verändern. Einen leeren Wert setzen Sie über setEmptyValue().

addInteger(string $name, $label=null): TextInput

Fügt ein Feld zur Eingabe einer ganzen Zahl hinzu (Klasse TextInput). Gibt entweder eine ganze Zahl zurück oder null, wenn der Benutzer nichts eingibt.

$form->addInteger('year', 'Jahr:')
	->addRule($form::Range, 'Das Jahr muss zwischen %d und %d liegen.', [1900, 2023]);

Das Element wird als <input type="number"> gerendert. Über die Methode setHtmlType() können Sie den Typ auf range ändern, um es als Schieberegler darzustellen, oder auf text, wenn Sie ein gewöhnliches Textfeld ohne das besondere Verhalten des Typs number vorziehen.

addFloat(string $name, $label=null): TextInput

Fügt ein Feld zur Eingabe einer Fließkommazahl hinzu (Klasse TextInput). Gibt entweder eine Fließkommazahl zurück oder null, wenn der Benutzer nichts eingibt.

$form->addFloat('level', 'Stufe:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Die Stufe muss zwischen %d und %d liegen.', [0, 100]);

Das Element wird als <input type="number"> gerendert. Über die Methode setHtmlType() können Sie den Typ auf range ändern, um es als Schieberegler darzustellen, oder auf text, wenn Sie ein gewöhnliches Textfeld ohne das besondere Verhalten des Typs number vorziehen.

Nette und der Browser Chrome akzeptieren als Dezimaltrennzeichen sowohl das Komma als auch den Punkt. Damit das auch in Firefox funktioniert, empfiehlt es sich, das Attribut lang entweder für das jeweilige Element oder für die ganze Seite zu setzen, zum Beispiel <html lang="de">.

addEmail(string $name, $label=null, int $maxLength=255): TextInput

Fügt ein Feld zur Eingabe einer E-Mail-Adresse hinzu (Klasse TextInput). Füllt der Benutzer das Feld nicht aus, gibt es einen leeren String '' zurück; mit setNullable() sorgen Sie dafür, dass es stattdessen null zurückgibt.

$form->addEmail('email', 'E-Mail:');

Es prüft, ob der Wert eine gültige E-Mail-Adresse ist. Ob die Domain tatsächlich existiert, wird nicht geprüft, sondern nur die Syntax. Es validiert automatisch UTF-8 und schneidet Leerraum am Anfang und Ende ab.

Die maximale Länge lässt sich mit setMaxLength() begrenzen. Die Methode addFilter() erlaubt es, den vom Benutzer eingegebenen Wert zu verändern. Einen leeren Wert setzen Sie über setEmptyValue().

addPassword(string $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, 'Das Passwort muss eine Ziffer enthalten', '.*[0-9].*');

Wird das Formular erneut angezeigt, ist das Feld leer. Es validiert automatisch UTF-8, schneidet Leerraum am Anfang und Ende ab und entfernt Zeilenumbrüche, die ein Angreifer senden könnte.

addCheckbox(string $name, $caption=null): Checkbox

Fügt eine Checkbox hinzu (Klasse Checkbox). Gibt true oder false zurück, je nachdem, ob sie angehakt ist.

$form->addCheckbox('agree', 'Ich stimme den Bedingungen zu')
	->setRequired('Sie müssen unseren Bedingungen zustimmen');

addCheckboxList(string $name, $label=null, ?array $items=null): CheckboxList

Fügt eine Liste von Checkboxen zur Auswahl mehrerer Elemente hinzu (Klasse CheckboxList). Gibt ein Array der Schlüssel der ausgewählten Elemente zurück. Die Methode getSelectedItems() gibt die ausgewählten Elemente als Schlüssel-Wert-Paare zurück.

$form->addCheckboxList('colors', 'Farben:', [
	'r' => 'rot',
	'g' => 'grün',
	'b' => 'blau',
]);

Das Array der angebotenen Elemente übergeben Sie als dritten Parameter oder über die Methode setItems(). Übergeben Sie setItems() als zweites Argument false, werden die Werte zugleich als Schlüssel verwendet.

Mit setDisabled(['r', 'g']) deaktivieren Sie einzelne Elemente.

Das Element prüft automatisch, dass keine Fälschung stattgefunden hat und dass die ausgewählten Elemente tatsächlich zu den angebotenen gehören und nicht deaktiviert waren. Über die Methode getRawValue() lassen sich die gesendeten Elemente ohne diese wichtige Prüfung holen.

Beim Setzen der standardmäßig ausgewählten Elemente wird ebenfalls geprüft, dass sie zu den angebotenen gehören, sonst wirft es eine Exception. Diese Prüfung lässt sich mit checkDefaultValue(false) abschalten.

Wenn Sie das Formular mit der Methode GET absenden, können Sie eine kompaktere Art der Datenübertragung wählen, die Platz im Query-String spart. Sie aktivieren sie, indem Sie am Formular ein HTML-Attribut setzen:

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

addRadioList(string $name, $label=null, ?array $items=null): RadioList

Fügt Radiobuttons 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 statt des Schlüssels den Wert zurück.

$sex = [
	'm' => 'männlich',
	'f' => 'weiblich',
	'o' => 'anderes',
];
$form->addRadioList('gender', 'Geschlecht:', $sex);

Das Array der angebotenen Elemente übergeben Sie als dritten Parameter oder über die Methode setItems().

Mit setDisabled(['m']) deaktivieren Sie einzelne Elemente.

Das Element prüft automatisch, dass keine Fälschung stattgefunden hat und dass das ausgewählte Element tatsächlich zu den angebotenen gehört und nicht deaktiviert war. Über die Methode getRawValue() lässt sich das gesendete Element ohne diese wichtige Prüfung holen.

Beim Setzen des standardmäßig ausgewählten Elements wird ebenfalls geprüft, dass es zu den angebotenen gehört, sonst wirft es eine Exception. Diese Prüfung lässt sich mit checkDefaultValue(false) abschalten.

addSelect(string $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 statt des Schlüssels den Wert zurück.

$countries = [
	'CZ' => 'Tschechien',
	'SK' => 'Slowakei',
	'GB' => 'Großbritannien',
];

$form->addSelect('country', 'Land:', $countries)
	->setDefaultValue('SK');

Das Array der angebotenen Elemente übergeben Sie als dritten Parameter oder über die Methode setItems(). Die Elemente können auch ein zweidimensionales Array sein (das Optgroups darstellt):

$countries = [
	'Europe' => [
		'CZ' => 'Tschechien',
		'SK' => 'Slowakei',
		'GB' => 'Großbritannien',
	],
	'CA' => 'Kanada',
	'US' => 'USA',
	'?'  => 'anderes',
];

In Select-Boxen hat das erste Element oft eine besondere Bedeutung und dient als Aufforderung zum Handeln. Über die Methode setPrompt() fügen Sie ein solches Element hinzu.

$form->addSelect('country', 'Land:', $countries)
	->setPrompt('Wählen Sie ein Land');

Mit setDisabled(['CZ', 'SK']) deaktivieren Sie einzelne Elemente.

Das Element prüft automatisch, dass keine Fälschung stattgefunden hat und dass das ausgewählte Element tatsächlich zu den angebotenen gehört und nicht deaktiviert war. Über die Methode getRawValue() lässt sich das gesendete Element ohne diese wichtige Prüfung holen.

Beim Setzen des standardmäßig ausgewählten Elements wird ebenfalls geprüft, dass es zu den angebotenen gehört, sonst wirft es eine Exception. Diese Prüfung lässt sich mit checkDefaultValue(false) abschalten.

addMultiSelect(string $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 ausgewählten Elemente als Schlüssel-Wert-Paare zurück.

$form->addMultiSelect('countries', 'Länder:', $countries);

Das Array der angebotenen Elemente übergeben Sie als dritten Parameter oder über die Methode setItems(). Die Elemente können auch ein zweidimensionales Array sein.

Mit setDisabled(['CZ', 'SK']) deaktivieren Sie einzelne Elemente.

Das Element prüft automatisch, dass keine Fälschung stattgefunden hat und dass die ausgewählten Elemente tatsächlich zu den angebotenen gehören und nicht deaktiviert waren. Über die Methode getRawValue() lassen sich die gesendeten Elemente ohne diese wichtige Prüfung holen.

Beim Setzen der standardmäßig ausgewählten Elemente wird ebenfalls geprüft, dass sie zu den angebotenen gehören, sonst wirft es eine Exception. Diese Prüfung lässt sich mit checkDefaultValue(false) abschalten.

addUpload(string $name, $label=null): UploadControl

Fügt ein Feld zum Hochladen einer Datei hinzu (Klasse UploadControl). Gibt ein Objekt FileUpload zurück, auch wenn der Benutzer keine Datei hochgeladen hat, was sich über die Methode FileUpload::hasFile() prüfen lässt. Mit setNullable() sorgen Sie dafür, dass das Element null statt eines FileUpload-Objekts zurückgibt, wenn keine Datei hochgeladen wurde.

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Der Avatar muss JPEG, PNG, GIF, WebP oder AVIF sein.')
	->addRule($form::MaxFileSize, 'Die maximale Größe beträgt 1 MB.', 1024 * 1024);

Lässt sich die Datei nicht korrekt hochladen, wird das Formular nicht erfolgreich abgesendet und ein Fehler angezeigt. Nach erfolgreichem Absenden muss die Methode FileUpload::isOk() also nicht geprüft werden.

Vertrauen Sie niemals dem ursprünglichen Dateinamen, den die Methode FileUpload::getName() zurückgibt; der Client könnte einen bösartigen Dateinamen gesendet haben, um Ihre Anwendung zu beschädigen oder zu kapern.

Die Regeln MimeType und Image erkennen den verlangten Typ anhand der Signatur der Datei und prüfen ihre Unversehrtheit nicht. Ob ein Bild beschädigt ist, lässt sich zum Beispiel durch den Versuch feststellen, es zu laden.

addMultiUpload(string $name, $label=null): UploadControl

Fügt ein Feld zum Hochladen mehrerer Dateien auf einmal hinzu (Klasse UploadControl). Gibt ein Array von FileUpload-Objekten zurück. Die Methode FileUpload::hasFile() gibt für jedes von ihnen true zurück.

$form->addMultiUpload('files', 'Dateien:')
	->addRule($form::MaxLength, 'Es lassen sich höchstens %d Dateien hochladen.', 10);

Lässt sich eine der Dateien nicht korrekt hochladen, wird das Formular nicht erfolgreich abgesendet und ein Fehler angezeigt. Nach erfolgreichem Absenden muss die Methode FileUpload::isOk() also nicht für jede Datei geprüft werden.

Vertrauen Sie niemals den ursprünglichen Dateinamen, die die Methode FileUpload::getName() zurückgibt; der Client könnte bösartige Dateinamen gesendet haben, um Ihre Anwendung zu beschädigen oder zu kapern.

Die Regeln MimeType und Image erkennen den verlangten Typ anhand der Signatur der Datei und prüfen ihre Unversehrtheit nicht. Ob ein Bild beschädigt ist, lässt sich zum Beispiel durch den Versuch feststellen, es zu laden.

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

Fügt ein Feld hinzu, in dem der Benutzer bequem ein Datum aus Jahr, Monat und Tag eingeben kann (Klasse DateTimeControl).

Als Standardwert akzeptiert es Objekte, die DateTimeInterface implementieren, einen String mit einer Zeitangabe oder eine Zahl, die einen UNIX-Timestamp darstellt. Dasselbe gilt für die Argumente der Regeln Min, Max und Range, die das früheste und späteste erlaubte Datum festlegen.

$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. Über die Methode setFormat() können Sie ein Textformat oder einen Timestamp angeben:

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

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

Fügt ein Feld hinzu, in dem der Benutzer bequem eine Zeit aus Stunden, Minuten und wahlweise Sekunden eingeben kann (Klasse DateTimeControl).

Als Standardwert akzeptiert es Objekte, die DateTimeInterface implementieren, einen String mit einer Zeitangabe oder eine Zahl, die einen UNIX-Timestamp darstellt. Aus diesen Eingaben wird nur die Zeitangabe verwendet, das Datum wird ignoriert. Dasselbe gilt für die Argumente der Regeln Min, Max und Range, die die früheste und späteste erlaubte Zeit festlegen. Ist der gesetzte Mindestwert höher als der Höchstwert, entsteht ein Zeitbereich über Mitternacht hinweg.

$form->addTime('time', 'Zeit:', withSeconds: true)
	->addRule($form::Range, 'Die Zeit muss zwischen %d und %d liegen.', ['12:30', '13:30']);

Standardmäßig gibt es ein DateTimeImmutable-Objekt zurück (mit dem Datum 1. Januar des Jahres 1). Über die Methode setFormat() können Sie ein Textformat angeben:

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

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

Fügt ein Feld hinzu, in dem der Benutzer bequem Datum und Zeit zugleich eingeben kann, also Jahr, Monat, Tag, Stunden, Minuten und wahlweise Sekunden (Klasse DateTimeControl).

Als Standardwert akzeptiert es Objekte, die DateTimeInterface implementieren, einen String mit einer Zeitangabe oder eine Zahl, die einen UNIX-Timestamp darstellt. Dasselbe gilt für die Argumente der Regeln Min, Max und Range, die das früheste und späteste erlaubte Datum samt Zeit festlegen.

$form->addDateTime('datetime', 'Datum und Zeit:')
	->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. Über die Methode setFormat() können Sie ein Textformat oder einen Timestamp angeben:

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

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

Fügt ein Feld zur Auswahl einer Farbe hinzu (Klasse ColorPicker). Die Farbe wird als String im Format #rrggbb zurückgegeben. Trifft der Benutzer keine Auswahl, gibt es Schwarz #000000 zurück.

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

addHidden(string $name, mixed $default=null): HiddenField

Fügt ein verstecktes Feld hinzu (Klasse HiddenField).

$form->addHidden('userid');

Mit setNullable() sorgen Sie dafür, dass es null statt eines leeren Strings zurückgibt. Die Methode addFilter() erlaubt es, den gesendeten Wert zu verändern.

Auch wenn das Element versteckt ist, muss Ihnen klar sein, dass sich sein Wert von einem Angreifer trotzdem verändern oder fälschen lässt. Prüfen und validieren Sie alle empfangenen Werte auf der Serverseite immer gründlich, um Sicherheitsrisiken durch Manipulation der Daten zu vermeiden.

addSubmit(string $name, $caption=null): SubmitButton

Fügt einen Absende-Button hinzu (Klasse SubmitButton).

$form->addSubmit('submit', 'Absenden');

Den Handler können Sie dem Button als dritten Parameter $onSubmit direkt übergeben, statt ihn an das Event onClick zu hängen:

$form->addSubmit('submit', 'Absenden', function (SubmitButton $button, $data): void {
	// ...
});

Ein Formular kann mehr als einen Absende-Button haben:

$form->addSubmit('register', 'Registrieren');
$form->addSubmit('cancel', 'Abbrechen');

Um festzustellen, welcher davon gedrückt wurde, verwenden Sie:

if ($form['register']->isSubmittedBy()) {
  // ...
}

Wenn Sie beim Drücken eines Buttons nicht das gesamte Formular validieren wollen (etwa bei den Buttons Abbrechen oder Vorschau), verwenden Sie setValidationScope().

addButton(string $name, $caption=null): Button

Fügt einen Button hinzu (Klasse Button), der keine Absendefunktion hat. Er lässt sich daher für andere Aufgaben nutzen, etwa um beim Klick eine JavaScript-Funktion aufzurufen.

$form->addButton('raise', 'Gehalt erhöhen')
	->setHtmlAttribute('onclick', 'raiseSalary()');

addImageButton(string $name, ?string $src=null, ?string $alt=null): ImageButton

Fügt einen Absende-Button in Form eines Bildes hinzu (Klasse ImageButton).

$form->addImageButton('submit', '/path/to/image.png', 'Absenden');

Verwenden Sie mehrere Absende-Buttons, stellen Sie über $form['submit']->isSubmittedBy() fest, welcher davon gedrückt wurde.

addContainer(string|int $name): Container

Fügt ein Unterformular hinzu (Klasse Container), also einen Container, dem sich weitere Elemente auf dieselbe Weise hinzufügen lassen wie dem Formular. Methoden wie setDefaults() oder getValues() funktionieren ebenfalls.

$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 (eine vollständige Übersicht bietet die API-Dokumentation):

setDefaultValue($value) setzt den Standardwert
getValue() holt den aktuellen Wert
setOmitted() Ausgelassene Werte
setDisabled() Elemente deaktivieren

Rendering:

setCaption($caption) ändert das Label des Elements
setTranslator($translator) setzt den Übersetzer
setHtmlAttribute($name, $value) setzt ein HTML-Attribut des Elements
setHtmlId($id) setzt das HTML-Attribut id
setOption($key, $value) setzt die Optionen für das Rendering

Validierung:

setRequired() macht das Element zum Pflichtfeld
addRule() fügt eine Validierungsregel hinzu
addCondition(), addConditionOn() setzt eine Validierungsbedingung
addError($message) fügt eine Fehlermeldung hinzu

Für die Elemente addText(), addPassword(), addTextArea(), addEmail(), addInteger(), addFloat() lassen sich die folgenden Methoden aufrufen:

setNullable() legt fest, ob getValue() statt eines leeren Strings null zurückgibt
setEmptyValue($value) setzt einen besonderen Wert, der als leerer String gilt
setMaxLength($length) setzt die maximal erlaubte Anzahl von Zeichen
addFilter($filter) verändert die Eingabe

Ausgelassene Werte

Wenn uns der vom Benutzer eingegebene Wert nicht interessiert, können wir ihn mit setOmitted() aus dem Ergebnis der Methode $form->getValues() und aus den Daten für die Handler ausschließen. Das ist bei Feldern zur Bestätigung eines Passworts, bei Anti-Spam-Elementen und Ähnlichem nützlich.

$form->addPassword('passwordVerify', 'Passwort erneut:')
	->setRequired('Geben Sie das Passwort zur Kontrolle erneut ein')
	->addRule($form::Equal, 'Die Passwörter stimmen nicht überein', $form['password'])
	->setOmitted();

Elemente deaktivieren

Elemente lassen sich mit setDisabled() deaktivieren. Ein deaktiviertes Element kann der Benutzer nicht bearbeiten.

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

Deaktivierte Elemente sendet der Browser gar nicht erst an den Server, Sie finden sie also nicht in den Daten, die die Funktion $form->getValues() zurückgibt. Setzen Sie jedoch setOmitted(false), nimmt Nette ihren Standardwert in diese Daten auf.

Beim Aufruf von setDisabled() wird der Wert des Elements aus Sicherheitsgründen gelöscht. Wenn Sie einen Standardwert setzen, müssen Sie das also nach dem Deaktivieren tun:

$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. Auch wenn das Element nur lesbar ist, muss Ihnen klar sein, dass sich sein Wert von einem Angreifer trotzdem verändern oder fälschen lässt.

Eigene Elemente

Neben der breiten Palette eingebauter Formularelemente können Sie dem Formular eigene Elemente hinzufügen:

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

Wie sich ein solches Element schreiben lässt, samt Einlesen der gesendeten Daten, Validierung und Rendering, beschreibt ein eigenes Kapitel. Dort erfahren Sie auch etwas über Extension-Methoden, mit denen Sie sich eine eigene Methode zum Hinzufügen wie $form->addZip() schreiben können.

Low-Level-Elemente

Sie können auch Elemente verwenden, die nur im Template stehen und dem Formular über keine der Methoden $form->addXyz() hinzugefügt wurden. Wenn wir zum Beispiel Datensätze aus einer Datenbank auflisten und vorher nicht wissen, wie viele es sein werden und welche IDs sie haben, und für jede Zeile eine Checkbox oder einen Radiobutton anzeigen wollen, schreiben wir das einfach ins Template:

{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}

Und nach dem Absenden holen wir den Wert:

$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');

Der erste Parameter ist dabei der Typ des Elements (DataFile für type=file, DataLine für einzeilige Eingaben wie text, password, email und so weiter, und DataText für alle übrigen), der zweite Parameter sel[] entspricht dem HTML-Attribut name. Den Typ des Elements können wir mit dem Wert DataKeys kombinieren, der die Schlüssel der Elemente erhält. Besonders nützlich ist das bei select, radioList und checkboxList.

Entscheidend ist, dass getHttpData() einen bereinigten Wert zurückgibt. In diesem Fall wird es immer ein Array gültiger UTF-8-Strings sein, ganz gleich, was ein Angreifer an den Server zu senden versucht. Das ist analog zur direkten Arbeit mit $_POST oder $_GET, mit dem wesentlichen Unterschied, dass es immer saubere Daten zurückgibt, so wie Sie es von den Standard-Formularelementen von Nette gewohnt sind.