Formular-Steuerelemente

Übersicht über die eingebauten Formularsteuerelemente.

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

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

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

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

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

Verwenden Sie setHtmlType(), um das Zeichen des Eingabeelements in search, tel, url, range, date, datetime-local, month, time, week, color zu ändern. Anstelle der Typen number und email empfehlen wir die Verwendung von addInteger und addEmail, die eine serverseitige Validierung ermöglichen.

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

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

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

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

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

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

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

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

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

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

$form->addInteger('level', 'Level:')
	->setDefaultValue(0)
	->addRule($form::Range, 'Level must be between %d and %d.', [0, 100]);

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

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

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

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

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

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

Fügt Passwortfeld hinzu (Klasse TextInput).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Fügt ein Datei-Upload-Feld hinzu (Klasse UploadControl). Gibt das FileUpload-Objekt zurück, auch wenn der Benutzer keine Datei hochgeladen hat, was mit der Methode FileUpload::hasFile() herausgefunden werden kann.

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatar must be JPEG, PNG, GIF or WebP')
	->addRule($form::MaxFileSize, 'Maximum size is 1 MB', 1024 * 1024);

Wenn die Datei nicht korrekt hochgeladen wurde, wurde das Formular nicht erfolgreich abgeschickt und es wird ein Fehler angezeigt. D.h. es ist nicht notwendig, die Methode FileUpload::isOk() zu überprüfen.

Vertrauen Sie nicht auf den ursprünglichen Dateinamen, der von der Methode FileUpload::getName() zurückgegeben wird.

Die Regeln MimeType und Image erkennen den gewünschten Typ einer Datei oder eines Bildes anhand ihrer Signatur. Die Integrität der gesamten Datei wird nicht geprüft. Sie können herausfinden, ob ein Bild nicht beschädigt ist, indem Sie beispielsweise versuchen, es zu laden.

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

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

$form->addMultiUpload('files', 'Files:')
	->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);

Wenn eine der Dateien nicht korrekt hochgeladen werden kann, wurde das Formular nicht erfolgreich übermittelt und es wird ein Fehler angezeigt. Es ist also nicht notwendig, die Methode FileUpload::isOk() zu überprüfen.

Vertrauen Sie nicht auf die von der Methode FileUpload::getName() zurückgegebenen Originaldateinamen. Ein Client könnte einen bösartigen Dateinamen mit der Absicht senden, Ihre Anwendung zu beschädigen oder zu hacken.

Die Regeln MimeType und Image erkennen den gewünschten Typ einer Datei oder eines Bildes anhand ihrer Signatur. Die Integrität der gesamten Datei wird nicht geprüft. Sie können herausfinden, ob ein Bild nicht beschädigt ist, indem Sie beispielsweise versuchen, es zu laden.

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

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

$form->addHidden('userid');

Verwenden Sie setNullable(), um die Rückgabe von null anstelle eines leeren Strings zu ändern. Mit addFilter() können Sie den übergebenen Wert ändern.

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

Fügt die Schaltfläche Submit (Klasse SubmitButton) hinzu.

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

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

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

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

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

Wenn Sie das Formular nicht validieren wollen, wenn ein Submit-Button gedrückt wird (wie Abbrechen oder Vorschau), können Sie dies mit setValidationScope() ausschalten.

addButton(string|int $name, $caption): Button

Fügt eine Schaltfläche (Klasse Button) ohne Sendefunktion hinzu. Sie ist nützlich, um andere Funktionen an die id zu binden, zum Beispiel eine JavaScript-Aktion.

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

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

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

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

Wenn Sie mehrere Submit-Buttons verwenden, können Sie herausfinden, welcher Button angeklickt wurde mit $form['submit']->isSubmittedBy().

addContainer(string|int $name): Container

Fügt ein Unterformular (Klasse Container) oder einen Container hinzu, der genauso behandelt werden kann wie ein Formular. Das heißt, Sie können Methoden wie setDefaults() oder getValues() verwenden.

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Your name:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Your name:');
$sub2->addEmail('email', 'Email:');

Die gesendeten Daten werden dann als multidimensionale Struktur zurückgegeben:

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

Übersicht der Einstellungen

Für alle Elemente können wir die folgenden Methoden aufrufen (siehe API-Dokumentation für eine vollständige Übersicht):

Rendering:

Validierung:

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

Ausgelassene Werte

Wenn Sie an dem vom Benutzer eingegebenen Wert nicht interessiert sind, können wir setOmitted() verwenden, um ihn aus dem Ergebnis auszulassen, das von der Methode $form->getValues​() geliefert oder an Handler übergeben wird. Dies eignet sich für verschiedene Passwörter zur Überprüfung, Antispam-Felder usw.

$form->addPassword('passwordVerify', 'Password again:')
	->setRequired('Fill your password again to check for typo')
	->addRule($form::Equal, 'Password mismatch', $form['password'])
	->setOmitted();

Deaktivieren von Eingaben

Um eine Eingabe zu deaktivieren, können Sie setDisabled() aufrufen. Ein solches Feld kann vom Benutzer nicht bearbeitet werden.

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

Beachten Sie, dass der Browser die deaktivierten Felder gar nicht an den Server sendet, so dass Sie sie nicht einmal in den von der Funktion $form->getValues() zurückgegebenen Daten finden werden.

Wenn Sie einen Standardwert für ein Feld festlegen, dürfen Sie dies erst tun, nachdem Sie das Feld deaktiviert haben:

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

Benutzerdefinierte Steuerelemente

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

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

Das Formular ist ein Abkömmling der Klasse Container und die Elemente sind Abkömmlinge von Component.

Es gibt eine Möglichkeit, neue Formularmethoden zu definieren, um benutzerdefinierte Elemente hinzuzufügen (z. B. $form->addZip()). Dies sind die sogenannten Erweiterungsmethoden. Der Nachteil ist, dass Codehinweise in Editoren für sie nicht funktionieren.

use Nette\Forms\Container;

// fügt Methode addZip(string $name, string $label = null)
Container::extensionMethod('addZip', function (Container $form, string $name, string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'Mindestens 5 Zahlen', '[0-9]{5}');
});

// Verwendung
$form->addZip('zip', 'Postleitzahl:');

Low-Level-Felder

Um ein Element zum Formular hinzuzufügen, müssen Sie nicht $form->addXyz() aufrufen. Formularelemente können stattdessen ausschließlich in Vorlagen eingeführt werden. Dies ist nützlich, wenn Sie z. B. dynamische Elemente erzeugen müssen:

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

Nach dem Absenden können Sie die Werte abrufen:

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

Im ersten Parameter geben Sie den Elementtyp an (DataFile für type=file, DataLine für einzeilige Eingaben wie text, password oder email und DataText für die übrigen). Der zweite Parameter entspricht dem HTML-Attribut name. Wenn Sie Schlüssel beibehalten müssen, können Sie den ersten Parameter mit DataKeys kombinieren. Dies ist nützlich für select, radioList oder checkboxList.

getHttpData() gibt die bereinigte Eingabe zurück. In diesem Fall handelt es sich immer um ein Array gültiger UTF-8-Strings, unabhängig davon, was der Angreifer über das Formular gesendet hat. Es ist eine Alternative zur direkten Arbeit mit $_POST oder $_GET, wenn Sie sichere Daten erhalten möchten.