Formulare Rendering
*******************

Das Erscheinungsbild von Formularen kann sehr unterschiedlich sein. In der Praxis können wir auf zwei Extreme stoßen. Einerseits besteht die Notwendigkeit, eine Reihe von Formularen in einer Anwendung darzustellen, die sich optisch ähneln, und wir schätzen die einfache Darstellung ohne Vorlage mit `$form->render()`. Dies ist normalerweise bei Verwaltungsschnittstellen der Fall.

Andererseits gibt es verschiedene Formulare, von denen jedes einzelne einzigartig ist. Ihr Aussehen wird am besten durch die HTML-Sprache in der Vorlage beschrieben. Und natürlich werden wir neben den beiden genannten Extremen auch viele Formulare finden, die irgendwo dazwischen liegen.


Rendering mit Latte .[#toc-rendering-with-latte]
================================================

Das [Latte-Templating-System |latte:] erleichtert das Rendern von Formularen und ihren Elementen grundlegend. Wir werden zunächst zeigen, wie man Formulare manuell, Element für Element, rendern kann, um die volle Kontrolle über den Code zu erhalten. Später werden wir zeigen, wie man dieses Rendering [automatisieren |#Automatic rendering] kann.

Mit der Methode `Nette\Forms\Blueprint::latte($form)` können Sie sich den Vorschlag einer Lattenvorlage für das Formular generieren lassen, der dann auf der Browser-Seite ausgegeben wird. Dann brauchen Sie den Code nur noch mit einem Klick auszuwählen und in Ihr Projekt zu kopieren. .{data-version:3.1.15}


`{control}`
-----------

Der einfachste Weg, ein Formular zu rendern, ist, es in eine Vorlage zu schreiben:

```latte
{control signInForm}
```

Das Aussehen des gerenderten Formulars kann durch die Konfiguration des [Renderers |#Renderer] und [einzelner Steuerelemente |#HTML Attributes] verändert werden.


`n:name`
--------

Es ist sehr einfach, die Formulardefinition in PHP-Code mit HTML-Code zu verknüpfen. Fügen Sie einfach die `n:name` Attribute hinzu. So einfach ist das!

```php
protected function createComponentSignInForm(): Form
{
	$form = new Form;
	$form->addText('username')->setRequired();
	$form->addPassword('password')->setRequired();
	$form->addSubmit('send');
	return $form;
}
```

```latte
<form n:name=signInForm class=form>
	<div>
		<label n:name=username>Username: <input n:name=username size=20 autofocus></label>
	</div>
	<div>
		<label n:name=password>Password: <input n:name=password></label>
	</div>
	<div>
		<input n:name=send class="btn btn-default">
	</div>
</form>
```

Das Aussehen des resultierenden HTML-Codes liegt ganz in Ihrer Hand. Wenn Sie das Attribut `n:name` mit `<select>`, `<button>` oder `<textarea>` Elementen verwenden, wird deren interner Inhalt automatisch ausgefüllt.
Darüber hinaus erzeugt der `<form n:name>` Tag eine lokale Variable `$form` mit dem gezeichneten Formularobjekt und das schließende `</form>` zeichnet alle nicht gezeichneten versteckten Elemente (das gleiche gilt für `{form} ... {/form}`).

Wir dürfen jedoch nicht vergessen, mögliche Fehlermeldungen zu rendern. Sowohl solche, die durch die Methode `addError()` zu einzelnen Elementen hinzugefügt wurden (mit `{inputError}`), als auch solche, die direkt zum Formular hinzugefügt wurden (zurückgegeben von `$form->getOwnErrors()`):

```latte
<form n:name=signInForm class=form>
	<ul class="errors" n:ifcontent>
		<li n:foreach="$form->getOwnErrors() as $error">{$error}</li>
	</ul>

	<div>
		<label n:name=username>Username: <input n:name=username size=20 autofocus></label>
		<span class=error n:ifcontent>{inputError username}</span>
	</div>
	<div>
		<label n:name=password>Password: <input n:name=password></label>
		<span class=error n:ifcontent>{inputError password}</span>
	</div>
	<div>
		<input n:name=send class="btn btn-default">
	</div>
</form>
```

Komplexere Formularelemente, wie z. B. RadioList oder CheckboxList, können Element für Element gerendert werden:

```latte
{foreach $form[gender]->getItems() as $key => $label}
	<label n:name="gender:$key"><input n:name="gender:$key"> {$label}</label>
{/foreach}
```


`{label}` `{input}`
-------------------

Wollen Sie nicht für jedes Element überlegen, welches HTML-Element Sie dafür in der Vorlage verwenden wollen, ob `<input>`, `<textarea>` usw.? Die Lösung ist der universelle `{input}` Tag:

```latte
<form n:name=signInForm class=form>
	<ul class="errors" n:ifcontent>
		<li n:foreach="$form->getOwnErrors() as $error">{$error}</li>
	</ul>

	<div>
		{label username}Username: {input username, size: 20, autofocus: true}{/label}
		{inputError username}
	</div>
	<div>
		{label password}Password: {input password}{/label}
		{inputError password}
	</div>
	<div>
		{input send, class: "btn btn-default"}
	</div>
</form>
```

Wenn das Formular einen Übersetzer verwendet, wird der Text innerhalb der `{label}` Tags übersetzt.

Auch hier gilt, dass komplexere Formularelemente wie RadioList oder CheckboxList Element für Element gerendert werden können:

```latte
{foreach $form[gender]->items as $key => $label}
	{label gender:$key}{input gender:$key} {$label}{/label}
{/foreach}
```

Zum Rendern des `<input>` selbst im Element Checkbox zu rendern, verwenden Sie `{input myCheckbox:}`. HTML-Attribute müssen durch ein Komma getrennt werden `{input myCheckbox:, class: required}`.


`{inputError}`
--------------

Gibt eine Fehlermeldung für das Formularelement aus, wenn es eine hat. Die Meldung wird normalerweise in ein HTML-Element zur Gestaltung eingeschlossen.
Die Vermeidung der Darstellung eines leeren Elements, wenn es keine Meldung gibt, kann elegant mit `n:ifcontent` erfolgen:

```latte
<span class=error n:ifcontent>{inputError $input}</span>
```

Wir können das Vorhandensein eines Fehlers mit der Methode `hasErrors()` erkennen und die Klasse des übergeordneten Elements entsprechend einstellen:

```latte
<div n:class="$form[username]->hasErrors() ? 'error'">
	{input username}
	{inputError username}
</div>
```


`{form}`
--------

Tags `{form signInForm}...{/form}` sind eine Alternative zu `<form n:name="signInForm">...</form>`.


Automatisches Rendering .[#toc-automatic-rendering]
---------------------------------------------------

Mit den Tags `{input}` und `{label}` können wir auf einfache Weise eine generische Vorlage für ein beliebiges Formular erstellen. Sie durchläuft alle Elemente des Formulars und rendert sie nacheinander, mit Ausnahme der versteckten Elemente, die automatisch gerendert werden, wenn das Formular mit dem `</form>` Tag beendet wird.
Sie erwartet den Namen des gerenderten Formulars in der Variablen `$form`.

```latte
<form n:name=$form class=form>
	<ul class="errors" n:ifcontent>
		<li n:foreach="$form->getOwnErrors() as $error">{$error}</li>
	</ul>

	<div n:foreach="$form->getControls() as $input"
		n:if="$input->getOption(type) !== hidden">
		{label $input /}
		{input $input}
		{inputError $input}
	</div>
</form>
```

Die verwendeten selbstschließenden Paar-Tags `{label .../}` zeigen die Bezeichnungen aus der Formulardefinition im PHP-Code an.

Sie können diese generische Vorlage in der Datei `basic-form.latte` speichern und das Formular rendern, indem Sie es einbinden und den Formularnamen (oder die Instanz) an den Parameter `$form` übergeben:

```latte
{include basic-form.latte, form: signInForm}
```

Wenn Sie das Aussehen eines bestimmten Formulars beeinflussen und ein Element anders zeichnen möchten, ist es am einfachsten, in der Vorlage Blöcke vorzubereiten, die später überschrieben werden können.
Blöcke können auch [dynamische Namen |latte:template-inheritance#dynamic-block-names] haben, so dass Sie den Namen des zu zeichnenden Elements in sie einfügen können. Zum Beispiel:

```latte
...
	{label $input /}
	{block "input-{$input->name}"}{input $input}{/block}
...
```

Für das Element z.B. `username` wird der Block `input-username` erstellt, der mit dem Tag [{embed} |latte:template-inheritance#unit-inheritance] einfach überschrieben werden kann:

```latte
{embed basic-form.latte, form: signInForm}
	{block input-username}
		<span class=important>
			{include parent}
		</span>
	{/block}
{/embed}
```

Alternativ kann auch der gesamte Inhalt der Vorlage `basic-form.latte` als Block [definiert |latte:template-inheritance#definitions] werden, einschließlich des Parameters `$form`:

```latte
{define basic-form, $form}
	<form n:name=$form class=form>
		...
	</form>
{/define}
```

Dadurch wird die Verwendung etwas einfacher:

```latte
{embed basic-form, signInForm}
	...
{/embed}
```

Sie brauchen den Block nur noch an einer Stelle zu importieren, nämlich am Anfang der Layout-Vorlage:

```latte
{import basic-form.latte}
```


Besondere Fälle .[#toc-special-cases]
-------------------------------------

Wenn Sie nur den inneren Teil des Formulars ohne HTML-Tags darstellen wollen `<form>`darstellen wollen, z. B. beim Senden von Snippets, blenden Sie diese mit dem Attribut `n:tag-if` aus:

```latte
<form n:name=signInForm n:tag-if=false>
	<div>
		<label n:name=username>Username: <input n:name=username></label>
		{inputError username}
	</div>
</form>
```

Das Tag `formContainer` hilft beim Rendern von Eingaben innerhalb eines Formular-Containers.

```latte
<p>Which news you wish to receive:</p>

{formContainer emailNews}
<ul>
	<li>{input sport} {label sport /}</li>
	<li>{input science} {label science /}</li>
</ul>
{/formContainer}
```


Rendering ohne Latte .[#toc-rendering-without-latte]
====================================================

Der einfachste Weg, ein Formular zu rendern, ist der Aufruf:

```php
$form->render();
```

Das Aussehen des gerenderten Formulars kann durch Konfiguration des [Renderers |#Renderer] und [einzelner Steuerelemente |#HTML Attributes] geändert werden.


Manuelles Rendering .[#toc-manual-rendering]
--------------------------------------------

Jedes Formularelement hat Methoden, die den HTML-Code für das Formularfeld und die Beschriftung erzeugen. Sie können ihn entweder als String oder als [Nette\Utils\Html-Objekt |utils:html-elements] zurückgeben:

- `getControl(): Html|string` gibt den HTML-Code des Elements zurück
- `getLabel($caption = null): Html|string|null` gibt den HTML-Code der Beschriftung zurück, falls vorhanden

So kann das Formular Element für Element gerendert werden:

```php
<?php $form->render('begin') ?>
<?php $form->render('errors') ?>

<div>
	<?= $form['name']->getLabel() ?>
	<?= $form['name']->getControl() ?>
	<span class=error><?= htmlspecialchars($form['name']->getError()) ?></span>
</div>

<div>
	<?= $form['age']->getLabel() ?>
	<?= $form['age']->getControl() ?>
	<span class=error><?= htmlspecialchars($form['age']->getError()) ?></span>
</div>

// ...

<?php $form->render('end') ?>
```

Während für einige Elemente `getControl()` ein einzelnes HTML-Element zurückgibt (z. B. `<input>`, `<select>` usw.), gibt es für andere ein ganzes Stück HTML-Code zurück (CheckboxList, RadioList).
In diesem Fall können Sie Methoden verwenden, die einzelne Eingaben und Beschriftungen für jedes Element separat erzeugen:

- `getControlPart($key = null): ?Html` gibt den HTML-Code eines einzelnen Elements zurück
- `getLabelPart($key = null): ?Html` gibt den HTML-Code für die Beschriftung eines einzelnen Eintrags zurück

.[note]
Aus historischen Gründen wird diesen Methoden das Präfix `get` vorangestellt, aber `generate` wäre besser, da es bei jedem Aufruf ein neues Element `Html` erzeugt und zurückgibt.


Renderer .[#toc-renderer]
=========================

Es handelt sich um ein Objekt, das das Rendering des Formulars ermöglicht. Es kann durch die Methode `$form->setRenderer` gesetzt werden. Es wird beim Aufruf der Methode `$form->render()` an die Kontrolle übergeben.

Wenn wir keinen benutzerdefinierten Renderer festlegen, wird der Standard-Renderer [api:Nette\Forms\Rendering\DefaultFormRenderer] verwendet. Dieser rendert die Formularelemente als HTML-Tabelle. Die Ausgabe sieht wie folgt aus:

```latte
<table>
<tr class="required">
	<th><label class="required" for="frm-name">Name:</label></th>

	<td><input type="text" class="text" name="name" id="frm-name" required value=""></td>
</tr>

<tr class="required">
	<th><label class="required" for="frm-age">Age:</label></th>

	<td><input type="text" class="text" name="age" id="frm-age" required value=""></td>
</tr>

<tr>
	<th><label>Gender:</label></th>
	...
```

Es bleibt Ihnen überlassen, ob Sie eine Tabelle verwenden oder nicht, und viele Webdesigner bevorzugen andere Auszeichnungen, zum Beispiel eine Liste. Wir können `DefaultFormRenderer` so konfigurieren, dass es überhaupt nicht in eine Tabelle gerendert wird. Wir müssen nur die richtigen [$wrappers |api:Nette\Forms\Rendering\DefaultFormRenderer::$wrappers] setzen. Der erste Index steht immer für einen Bereich und der zweite für ein Element. Alle entsprechenden Bereiche sind im Bild zu sehen:

[* form-areas-en.webp *]

Standardmäßig wird eine Gruppe von `controls` in `<table>`eingeschlossen, und jede `pair` ist eine Tabellenzeile `<tr>` mit einem Paar von `label` und `control` (Zellen `<th>` und `<td>`). Lassen Sie uns all diese Umhüllungselemente ändern. Wir packen `controls` in `<dl>`ein, belassen `pair` für sich, fügen `label` in `<dt>` und verpacken `control` in `<dd>`:

```php
$renderer = $form->getRenderer();
$renderer->wrappers['controls']['container'] = 'dl';
$renderer->wrappers['pair']['container'] = null;
$renderer->wrappers['label']['container'] = 'dt';
$renderer->wrappers['control']['container'] = 'dd';

$form->render();
```

Das Ergebnis ist der folgende Ausschnitt:

```latte
<dl>
	<dt><label class="required" for="frm-name">Name:</label></dt>

	<dd><input type="text" class="text" name="name" id="frm-name" required value=""></dd>


	<dt><label class="required" for="frm-age">Age:</label></dt>

	<dd><input type="text" class="text" name="age" id="frm-age" required value=""></dd>


	<dt><label>Gender:</label></dt>
	...
</dl>
```

Wrapper können viele Attribute beeinflussen. Zum Beispiel:

- spezielle CSS-Klassen zu jeder Formulareingabe hinzufügen
- Unterscheidung zwischen ungeraden und geraden Zeilen
- Erforderliche und optionale Zeichen unterschiedlich gestalten
- einstellen, ob Fehlermeldungen oberhalb des Formulars oder in der Nähe der einzelnen Elemente angezeigt werden


Optionen .[#toc-options]
------------------------

Das Verhalten von Renderer kann auch durch das Setzen von *Optionen* für einzelne Formularelemente gesteuert werden. Auf diese Weise können Sie den Tooltip einstellen, der neben dem Eingabefeld angezeigt wird:

```php
$form->addText('phone', 'Number:')
	->setOption('description', 'This number will remain hidden');
```

Wenn wir einen HTML-Inhalt darin platzieren wollen, verwenden wir die Klasse [Html |utils:html-elements].

```php
use Nette\Utils\Html;

$form->addText('phone', 'Phone:')
	->setOption('description', Html::el('p')
		->setHtml('<a href="...">Terms of service.</a>')
	);
```

.[tip]
Das Html-Element kann auch anstelle des Labels verwendet werden: `$form->addCheckbox('conditions', $label)`.


Eingaben gruppieren .[#toc-grouping-inputs]
-------------------------------------------

Renderer ermöglicht die Gruppierung von Elementen in visuelle Gruppen (Fieldsets):

```php
$form->addGroup('Personal data');
```

Durch das Erstellen einer neuen Gruppe wird diese aktiviert - alle weiteren Elemente werden dieser Gruppe hinzugefügt. Sie können ein Formular wie folgt erstellen:

```php
$form = new Form;
$form->addGroup('Personal data');
$form->addText('name', 'Your name:');
$form->addInteger('age', 'Your age:');
$form->addEmail('email', 'Email:');

$form->addGroup('Shipping address');
$form->addCheckbox('send', 'Ship to address');
$form->addText('street', 'Street:');
$form->addText('city', 'City:');
$form->addSelect('country', 'Country:', $countries);
```

Der Renderer zeichnet zuerst die Gruppen und dann die Elemente, die zu keiner Gruppe gehören.


Bootstrap-Unterstützung .[#toc-bootstrap-support]
-------------------------------------------------

Sie können [Beispiele |https://github.com/nette/forms/tree/master/examples] für die Konfiguration des Renderers für [Twitter Bootstrap 2 |https://github.com/nette/forms/blob/a0bc775b96b30780270bdec06396ca985168f11a/examples/bootstrap2-rendering.php#L58], [Bootstrap 3 |https://github.com/nette/forms/blob/a0bc775b96b30780270bdec06396ca985168f11a/examples/bootstrap3-rendering.php#L58] und [Bootstrap 4 |https://github.com/nette/forms/blob/96b3e90/examples/bootstrap4-rendering.php] finden


HTML-Attribute .[#toc-html-attributes]
======================================

Um beliebige HTML-Attribute für Formularelemente zu setzen, verwenden Sie die Methode `setHtmlAttribute(string $name, $value = true)`:

```php
$form->addInteger('number', 'Zahl:')
	->setHtmlAttribute('class', 'Große Zahl');

$form->addSelect('rank', 'Sortieren nach:', ['Preis', 'Name'])
	->setHtmlAttribute('onchange', 'submit()'); // ruft JS-Funktion submit() bei Änderung auf


// Zum Festlegen von Attributen der <form> selbst
$form->setHtmlAttribute('id', 'myForm');
```

Angabe der Art des Elements:

```php
$form->addText('tel', 'Your telephone:')
	->setHtmlType('tel')
	->setHtmlAttribute('placeholder', 'Please, fill in your telephone');
```

.[warning]
Das Setzen des Typs und anderer Attribute dient nur der visuellen Darstellung. Die Überprüfung der Korrektheit der Eingabe muss auf dem Server erfolgen, was Sie durch die Wahl eines geeigneten [Formularsteuerelements | controls] und die Festlegung von [Validierungsregeln | validation] sicherstellen können.

Für einzelne Elemente in Radio- oder Checkbox-Listen können wir ein HTML-Attribut mit unterschiedlichen Werten für jedes dieser Elemente setzen.
Beachten Sie den Doppelpunkt nach `style:`, der sicherstellt, dass der Wert anhand des Schlüssels ausgewählt wird:

```php
$colors = ['r' => 'red', 'g' => 'green', 'b' => 'blue'];
$styles = ['r' => 'background:red', 'g' => 'background:green'];
$form->addCheckboxList('colors', 'Colors:', $colors)
	->setHtmlAttribute('style:', $styles);
```

Renders:

```latte
<label><input type="checkbox" name="colors[]" style="background:red" value="r">red</label>
<label><input type="checkbox" name="colors[]" style="background:green" value="g">green</label>
<label><input type="checkbox" name="colors[]" value="b">blue</label>
```

Für das Setzen von booleschen Attributen, wie z. B. `readonly`, können wir die Notation mit einem Fragezeichen verwenden:

```php
$form->addCheckboxList('colors', 'Colors:', $colors)
	->setHtmlAttribute('readonly?', 'r'); // use array for multiple keys, e.g. ['r', 'g']
```

Renders:

```latte
<label><input type="checkbox" name="colors[]" readonly value="r">red</label>
<label><input type="checkbox" name="colors[]" value="g">green</label>
<label><input type="checkbox" name="colors[]" value="b">blue</label>
```

Bei Selectboxen setzt die Methode `setHtmlAttribute()` die Attribute des `<select>` Elements. Wenn wir die Attribute für jedes der folgenden Elemente setzen wollen
`<option>`setzen wollen, verwenden wir die Methode `setOptionAttribute()`. Auch der Doppelpunkt und das Fragezeichen, die oben verwendet wurden, funktionieren:

```php
$form->addSelect('colors', 'Colors:', $colors)
	->setOptionAttribute('style:', $styles);
```

Rendert:

```latte
<select name="colors">
	<option value="r" style="background:red">red</option>
	<option value="g" style="background:green">green</option>
	<option value="b">blue</option>
</select>
```


Prototypen .[#toc-prototypes]
-----------------------------

Eine alternative Möglichkeit, HTML-Attribute zu setzen, besteht darin, die Vorlage zu ändern, aus der das HTML-Element erzeugt wird. Das Template ist ein `Html` Objekt und wird von der Methode `getControlPrototype()` zurückgegeben:

```php
$input = $form->addInteger('number');
$html = $input->getControlPrototype(); // <input>
$html->class('big-number');            // <input class="big-number">
```

Die von `getLabelPrototype()` zurückgegebene Etikettenvorlage kann ebenfalls auf diese Weise geändert werden:

```php
$html = $input->getLabelPrototype(); // <label>
$html->class('unverwechselbar'); // <label class="unverwechselbar">
```

Für Checkbox-, CheckboxList- und RadioList-Elemente können Sie die Elementvorlage beeinflussen, die das Element umhüllt. Sie wird von `getContainerPrototype()` zurückgegeben. Standardmäßig ist es ein "leeres" Element, so dass nichts gerendert wird, aber wenn Sie ihm einen Namen geben, wird es gerendert:

```php
$input = $form->addCheckbox('send');
$html = $input->getContainerPrototype();
$html->setName('div'); // <div>
$html->class('check'); // <div class="check">
echo $input->getControl();
// <div class="check"><label><input type="checkbox" name="send"></label></div>
```

Im Falle von CheckboxList und RadioList ist es auch möglich, das von der Methode `getSeparatorPrototype()` zurückgegebene Elementtrennmuster zu beeinflussen. Standardmäßig ist es ein Element `<br>`. Wenn Sie es in ein Paarelement ändern, umhüllt es die einzelnen Elemente, anstatt sie zu trennen.
Es ist auch möglich, die HTML-Elementvorlage der Elementbeschriftungen zu beeinflussen, die `getItemLabelPrototype()` zurückgibt.


Übersetzen .[#toc-translating]
==============================

Wenn Sie eine mehrsprachige Anwendung programmieren, müssen Sie das Formular wahrscheinlich in verschiedenen Sprachen darstellen. Das Nette Framework definiert zu diesem Zweck eine Übersetzungsschnittstelle [api:Nette\Localization\Translator]. Es gibt keine Standardimplementierung in Nette, Sie können je nach Bedarf aus mehreren fertigen Lösungen wählen, die Sie auf [Componette |https://componette.org/search/localization] finden. Die Dokumentation beschreibt, wie Sie den Übersetzer konfigurieren können.

Das Formular unterstützt die Ausgabe von Text durch den Übersetzer. Wir übergeben ihn mit der Methode `setTranslator()`:

```php
$form->setTranslator($translator);
```

Von nun an werden nicht nur alle Beschriftungen, sondern auch alle Fehlermeldungen oder Selectbox-Einträge in eine andere Sprache übersetzt.

Es ist möglich, für einzelne Formularelemente einen anderen Übersetzer einzustellen oder die Übersetzung mit `null` komplett zu deaktivieren:

```php
$form->addSelect('carModel', 'Model:', $cars)
	->setTranslator(null);
```

Für [Validierungsregeln |validation] werden auch spezifische Parameter an den Übersetzer übergeben, zum Beispiel für die Regel:

```php
$form->addPassword('password', 'Password:')
	->addRule($form::MinLength, 'Password has to be at least %d characters long', 8)
```

Der Übersetzer wird mit den folgenden Parametern aufgerufen:

```php
$translator->translate('Password has to be at least %d characters long', 8);
```

und kann so die korrekte Pluralform für das Wort `characters` nach Anzahl wählen.


Ereignis onRender .[#toc-event-onrender]
========================================

Kurz bevor das Formular gerendert wird, können wir unseren Code aufrufen lassen. Dieser kann zum Beispiel HTML-Klassen zu den Formularelementen hinzufügen, damit sie richtig angezeigt werden. Wir fügen den Code in das Array `onRender` ein:

```php
$form->onRender[] = function ($form) {
	BootstrapCSS::initialize($form);
};
```