Formular-Steuerelemente

Übersicht über die eingebauten Formularsteuerelemente.

addText(string|int $name, $label=null): TextInput

Fügt ein einzeiliges Textfeld hinzu (Klasse TextInput). Wenn der Benutzer das Feld nicht ausfüllt, wird eine leere Zeichenkette '' zurückgegeben, oder verwenden Sie setNullable(), um dies zu ändern und null zurückzugeben.

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

Es validiert automatisch UTF-8, schneidet linke und rechte Leerzeichen ab und entfernt Zeilenumbrüche, die von einem Angreifer gesendet werden könnten.

Die maximale Länge kann mit setMaxLength() begrenzt werden. Mit addFilter() können Sie den vom Benutzer eingegebenen Wert ändern.

Mit setHtmlType() können Sie das Zeichen des Eingabeelements in search, tel, url, range, month, week, oder color ändern. Für andere Typen wie number, email, date, datetime-local und time gibt es separate Methoden addInteger, addFloat, addEmail, addDate, addTime und addDateTime, die über eine serverseitige Validierung verfügen.

$form->addText('color', 'Choose color:')
	->setHtmlType('color')
	->addRule($form::Pattern, 'invalid value', '[0-9a-f]{6}');

Für das Element kann der sogenannte empty-value gesetzt werden, der so etwas wie der Standardwert ist, aber, wenn der Benutzer ihn nicht überschreibt, einen leeren String oder null zurückgibt.

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

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

Fügt ein mehrzeiliges Textfeld (Klasse TextArea) hinzu. Wenn der Benutzer das Feld nicht ausfüllt, wird eine leere Zeichenkette '' zurückgegeben, oder verwenden Sie setNullable(), um dies zu ändern und null zurückzugeben.

$form->addTextArea('note', 'Note:')
	->addRule($form::MaxLength, 'Your note is way too long', 10000);

Validiert automatisch UTF-8 und normalisiert Zeilenumbrüche auf \n. Im Gegensatz zu einem einzeiligen Eingabefeld wird der Leerraum nicht abgeschnitten.

Die maximale Länge kann mit setMaxLength() begrenzt werden. Mit addFilter() können Sie den vom Benutzer eingegebenen Wert ändern. Mit setEmptyValue() können Sie den sogenannten Leerwert setzen.

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

Fügt Eingabefeld für Ganzzahl (Klasse TextInput) hinzu. Gibt entweder eine Ganzzahl oder null zurück, wenn der Benutzer nichts eingibt.

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

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]);

Nette und Chrome akzeptieren sowohl Komma als auch Punkt als Dezimaltrennzeichen. Damit Firefox auch ein Komma akzeptiert, müssen Sie die entsprechende Sprache im HTML-Attribut lang setzen, entweder direkt in diesem Element oder in einem übergeordneten Element, zum Beispiel <html lang="cs">.

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

Fügt ein E-Mail-Adressfeld mit Gültigkeitsprüfung hinzu (Klasse TextInput). Wenn der Benutzer das Feld nicht ausfüllt, wird eine leere Zeichenkette '' zurückgegeben, oder verwenden Sie setNullable(), um dies zu ändern und null zurückzugeben.

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

Überprüft, ob der Wert eine gültige E-Mail-Adresse ist. Es wird nicht überprüft, ob die Domäne tatsächlich existiert, nur die Syntax wird überprüft. Validiert automatisch UTF-8, schneidet linke und rechte Leerzeichen ab.

addPassword(string|int $name, $label=null): TextInput

Fügt Passwortfeld hinzu (Klasse TextInput).

$form->addPassword('password', 'Password:')
	->setRequired()
	->addRule($form::MinLength, 'Password has to be at least %d characters long', 8)
	->addRule($form::Pattern, 'Password must contain a number', '.*[0-9].*');

Wenn Sie das Formular erneut absenden, ist die Eingabe leer. Es validiert automatisch UTF-8, schneidet linke und rechte Leerzeichen ab und entfernt Zeilenumbrüche, die von einem Angreifer gesendet werden könnten.

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

Fügt ein Kontrollkästchen (Klasse Checkbox) hinzu. Das Feld gibt entweder true oder false zurück, je nachdem, ob es markiert ist.

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

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

Fügt eine Liste von Kontrollkästchen zur Auswahl mehrerer Elemente hinzu (Klasse CheckboxList). Gibt das Array der Schlüssel der ausgewählten Elemente zurück. Die Methode getSelectedItems() gibt Werte anstelle von Schlüsseln zurück.

$form->addCheckboxList('colors', 'Colors:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);

Wir übergeben das Array der Elemente als dritten Parameter oder mit der Methode setItems().

Sie können mit setDisabled(['r', 'g']) verwenden, um einzelne Elemente zu deaktivieren.

Das Element überprüft automatisch, dass keine Fälschung vorliegt und dass die ausgewählten Einträge tatsächlich zu den angebotenen gehören und nicht deaktiviert wurden. Die Methode getRawValue() kann verwendet werden, um eingereichte Artikel ohne diese wichtige Prüfung abzurufen.

Wenn Standardwerte gesetzt werden, wird auch geprüft, ob sie zu den angebotenen Artikeln gehören, andernfalls wird eine Ausnahme geworfen. Diese Prüfung kann mit checkDefaultValue(false) ausgeschaltet werden.

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

Fügt Optionsfelder hinzu (Klasse RadioList). Gibt den Schlüssel des ausgewählten Elements zurück, oder null, wenn der Benutzer nichts ausgewählt hat. Die Methode getSelectedItem() gibt einen Wert statt eines Schlüssels zurück.

$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);

Wir übergeben das Array der Elemente als dritten Parameter oder mit der Methode setItems().

Sie können mit setDisabled(['m']) verwenden, um einzelne Elemente zu deaktivieren.

Das Element überprüft automatisch, dass keine Fälschung vorliegt und dass das ausgewählte Element tatsächlich eines der angebotenen ist und nicht deaktiviert wurde. Die Methode getRawValue() kann verwendet werden, um das eingereichte Element ohne diese wichtige Prüfung abzurufen.

Wenn der Standardwert eingestellt ist, wird auch geprüft, ob es sich um einen der angebotenen Einträge handelt, andernfalls wird eine Ausnahme ausgelöst. Diese Prüfung kann mit checkDefaultValue(false) ausgeschaltet werden.

addSelect(string|int $name, $label=null, array $items=null): SelectBox

Fügt ein Auswahlfeld hinzu (Klasse SelectBox). Gibt den Schlüssel des ausgewählten Elements zurück, oder null, wenn der Benutzer nichts ausgewählt hat. Die Methode getSelectedItem() gibt einen Wert statt eines Schlüssels zurück.

$countries = [
	'CZ' => 'Czech republic',
	'SK' => 'Slovakia',
	'GB' => 'United Kingdom',
];

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

Wir übergeben das Array der Elemente als dritten Parameter oder mit der Methode setItems(). Das Array der Elemente kann auch zweidimensional sein:

$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];

Bei Auswahlfeldern hat der erste Eintrag oft eine besondere Bedeutung, er dient als Call-to-Action. Verwenden Sie die Methode setPrompt(), um einen solchen Eintrag hinzuzufügen.

$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');

Sie können mit setDisabled(['CZ', 'SK']) können Sie einzelne Einträge deaktivieren.

Das Element prüft automatisch, dass keine Fälschung vorliegt und dass das ausgewählte Element tatsächlich eines der angebotenen ist und nicht deaktiviert wurde. Die Methode getRawValue() kann verwendet werden, um das eingereichte Element ohne diese wichtige Prüfung abzurufen.

addMultiSelect(string|int $name, $label=null, array $items=null): MultiSelectBox

Fügt ein Auswahlfeld mit mehreren Auswahlmöglichkeiten hinzu (Klasse MultiSelectBox). Gibt das Array der Schlüssel der ausgewählten Elemente zurück. Die Methode getSelectedItems() gibt Werte anstelle von Schlüsseln zurück.

$form->addMultiSelect('countries', 'Countries:', $countries);

Wir übergeben das Array der Elemente als dritten Parameter oder mit der Methode setItems(). Das Array der Elemente kann auch zweidimensional sein.

Sie können mit setDisabled(['CZ', 'SK']) verwenden, um einzelne Elemente zu deaktivieren.

Das Element prüft automatisch, dass keine Fälschung vorliegt und dass die ausgewählten Einträge tatsächlich zu den angebotenen gehören und nicht deaktiviert wurden. Die Methode getRawValue() kann verwendet werden, um eingereichte Artikel ohne diese wichtige Prüfung abzurufen.

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.

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.