rendering.texy

Rendering dei moduli
********************

L'aspetto delle forme può essere molto vario. In pratica, si possono incontrare due estremi. Da un lato, c'è la necessità di rendere una serie di moduli in un'applicazione che siano visivamente simili tra loro e si apprezza la facilità di renderli senza un modello usando `$form->render()`. Questo è solitamente il caso delle interfacce amministrative.

D'altra parte, esistono vari moduli, ognuno dei quali è unico. Il loro aspetto è meglio descritto utilizzando il linguaggio HTML nel template. E naturalmente, oltre ai due estremi citati, incontreremo molti moduli che si collocano a metà strada.


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

Il [sistema di template Latte |latte:] facilita fondamentalmente il rendering dei moduli e dei loro elementi. In primo luogo, mostreremo come rendere i moduli manualmente, elemento per elemento, per ottenere il pieno controllo sul codice. In seguito mostreremo come [automatizzare |#Automatic rendering] tale rendering.

È possibile far generare la proposta di un modello Latte per il modulo utilizzando il metodo `Nette\Forms\Blueprint::latte($form)`, che lo invierà alla pagina del browser. È quindi sufficiente selezionare il codice con un clic e copiarlo nel progetto. .{data-version:3.1.15}


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

Il modo più semplice per rendere un modulo è scrivere in un modello:

```latte
{control signInForm}
```

L'aspetto del modulo renderizzato può essere modificato configurando il [Renderer |#Renderer] e i [singoli controlli |#HTML Attributes].


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

È estremamente facile collegare la definizione del modulo nel codice PHP con il codice HTML. Basta aggiungere gli attributi `n:name`. È facilissimo!

```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>
```

L'aspetto del codice HTML risultante è interamente nelle vostre mani. Se si utilizza l'attributo `n:name` con `<select>`, `<button>` o `<textarea>` il loro contenuto interno viene riempito automaticamente.
Inoltre, il tag `<form n:name>` crea una variabile locale `$form` con l'oggetto del modulo disegnato e la chiusura `</form>` disegna tutti gli elementi nascosti non disegnati (lo stesso vale per `{form} ... {/form}`).

Tuttavia, non bisogna dimenticare di rendere i possibili messaggi di errore. Sia quelli aggiunti ai singoli elementi dal metodo `addError()` (utilizzando `{inputError}`), sia quelli aggiunti direttamente al modulo (restituiti da `$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>
```

Elementi di form più complessi, come RadioList o CheckboxList, possono essere resi elemento per elemento:

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


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

Non si vuole pensare, per ogni elemento, a quale elemento HTML usare per esso nel template, se `<input>`, `<textarea>` ecc. La soluzione è il tag universale `{input}`:

```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>
```

Se il modulo utilizza un traduttore, il testo all'interno del tag `{label}` verrà tradotto.

Anche in questo caso, elementi di form più complessi, come RadioList o CheckboxList, possono essere resi elemento per elemento:

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

Per rendere l'elemento `<input>` nell'elemento Checkbox, utilizzare `{input myCheckbox:}`. Gli attributi HTML devono essere separati da una virgola `{input myCheckbox:, class: required}`.


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

Stampa un messaggio di errore per l'elemento del modulo, se ne ha uno. Il messaggio è solitamente avvolto in un elemento HTML per lo styling.
Evitare di rendere un elemento vuoto se non c'è un messaggio può essere fatto elegantemente con `n:ifcontent`:

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

Possiamo rilevare la presenza di un errore usando il metodo `hasErrors()` e impostare la classe dell'elemento genitore di conseguenza:

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


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

I tag `{form signInForm}...{/form}` sono un'alternativa a `<form n:name="signInForm">...</form>`.


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

Con i tag `{input}` e `{label}`, si può facilmente creare un modello generico per qualsiasi form. Esso itererà e renderà tutti i suoi elementi in modo sequenziale, tranne gli elementi nascosti, che vengono resi automaticamente quando il form viene terminato con il tag `</form>` .
Si aspetta il nome del form reso nella variabile `$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>
```

I tag a coppia autochiudente utilizzati `{label .../}` mostrano le etichette provenienti dalla definizione del modulo nel codice PHP.

Si può salvare questo modello generico nel file `basic-form.latte` e per rendere il modulo, basta includerlo e passare il nome del modulo (o l'istanza) al parametro `$form`:

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

Se si desidera influenzare l'aspetto di un particolare modulo e disegnare un elemento in modo diverso, il modo più semplice è preparare dei blocchi nel modello che possono essere sovrascritti in seguito.
I blocchi possono anche avere [nomi dinamici |latte:template-inheritance#dynamic-block-names], per cui è possibile inserire il nome dell'elemento da disegnare. Ad esempio:

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

Per l'elemento `username` viene creato il blocco `input-username`, che può essere facilmente sovrascritto utilizzando il tag [{embed} |latte:template-inheritance#unit-inheritance]:

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

In alternativa, l'intero contenuto del template `basic-form.latte` può essere [definito |latte:template-inheritance#definitions] come un blocco, compreso il parametro `$form`:

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

In questo modo sarà un po' più facile da usare:

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

È sufficiente importare il blocco in un solo punto, all'inizio del modello di layout:

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


Casi speciali .[#toc-special-cases]
-----------------------------------

Se si ha bisogno di rendere solo la parte interna del modulo senza tag HTML `<form>`ad esempio per l'invio di snippet, è possibile nasconderli utilizzando l'attributo `n:tag-if`:

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

Il tag `formContainer` aiuta a rendere gli input all'interno di un contenitore di form.

```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 senza Latte .[#toc-rendering-without-latte]
=====================================================

Il modo più semplice per rendere un modulo è chiamare:

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

L'aspetto del modulo renderizzato può essere modificato configurando il [Renderer |#Renderer] e i [singoli controlli |#HTML Attributes].


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

Ogni elemento del modulo ha metodi che generano il codice HTML per il campo e l'etichetta del modulo. Possono restituirlo sotto forma di stringa o di oggetto [Nette\Utils\Html |utils:html-elements]:

- `getControl(): Html|string` restituisce il codice HTML dell'elemento
- `getLabel($caption = null): Html|string|null` restituisce il codice HTML dell'eventuale etichetta

Questo permette di rendere il modulo elemento per elemento:

```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') ?>
```

Mentre per alcuni elementi `getControl()` restituisce un singolo elemento HTML (ad es. `<input>`, `<select>` ecc.), per altri restituisce un intero pezzo di codice HTML (CheckboxList, RadioList).
In questo caso, si possono usare metodi che generano input ed etichette individuali, per ogni elemento separatamente:

- `getControlPart($key = null): ?Html` restituisce il codice HTML di un singolo elemento
- `getLabelPart($key = null): ?Html` restituisce il codice HTML dell'etichetta di un singolo elemento

.[note]
Questi metodi hanno il prefisso `get` per ragioni storiche, ma sarebbe meglio `generate`, che crea e restituisce un nuovo elemento `Html` a ogni chiamata.


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

È un oggetto che fornisce il rendering del modulo. Può essere impostato dal metodo `$form->setRenderer`. Viene passato il controllo quando viene chiamato il metodo `$form->render()`.

Se non si imposta un renderer personalizzato, verrà utilizzato il renderer predefinito [api:Nette\Forms\Rendering\DefaultFormRenderer]. Questo renderà gli elementi del modulo come una tabella HTML. L'output appare come questo:

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

Sta a voi decidere se usare una tabella o meno e molti web designer preferiscono markup diversi, per esempio un elenco. Possiamo configurare `DefaultFormRenderer` in modo che non venga reso in una tabella. Basta impostare i [$wrapper |api:Nette\Forms\Rendering\DefaultFormRenderer::$wrappers] appropriati. Il primo indice rappresenta sempre un'area e il secondo un elemento. Tutte le rispettive aree sono mostrate nell'immagine:

[* form-areas-en.webp *]

Per impostazione predefinita, un gruppo di `controls` è avvolto in `<table>`e ogni `pair` è una riga di tabella `<tr>` contenente una coppia di `label` e `control` (celle `<th>` e `<td>`). Cambiamo tutti questi elementi wrapper. Avvolgeremo `controls` in `<dl>`lasciamo `pair` da solo, inseriamo `label` in `<dt>` e inseriamo `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();
```

Il risultato è il seguente snippet:

```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>
```

I wrapper possono influenzare molti attributi. Ad esempio:

- aggiungere classi CSS speciali a ciascun input del modulo
- distinguere tra linee pari e dispari
- disegnare in modo diverso gli elementi obbligatori e quelli opzionali
- impostare se i messaggi di errore vengono mostrati sopra il modulo o vicino a ogni elemento


Opzioni .[#toc-options]
-----------------------

Il comportamento del Renderer può essere controllato anche impostando delle *opzioni* sui singoli elementi del modulo. In questo modo è possibile impostare il tooltip che viene visualizzato accanto al campo di input:

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

Se si vuole inserire del contenuto HTML, si usa la classe [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]
L'elemento Html può essere utilizzato anche al posto di label: `$form->addCheckbox('conditions', $label)`.


Raggruppare gli input .[#toc-grouping-inputs]
---------------------------------------------

Il renderer consente di raggruppare gli elementi in gruppi visivi (fieldset):

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

La creazione di un nuovo gruppo lo attiva: tutti gli elementi aggiunti successivamente vengono aggiunti a questo gruppo. Si può costruire un modulo come questo:

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

Il renderer disegna prima i gruppi e poi gli elementi che non appartengono a nessun gruppo.


Supporto Bootstrap .[#toc-bootstrap-support]
--------------------------------------------

È possibile trovare [esempi |https://github.com/nette/forms/tree/master/examples] di configurazione del Renderer per [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] e [Bootstrap 4 |https://github.com/nette/forms/blob/96b3e90/examples/bootstrap4-rendering.php]


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

Per impostare attributi HTML arbitrari per gli elementi del modulo, utilizzare il metodo `setHtmlAttribute(string $name, $value = true)`:

```php
$form->addInteger('number', 'Number:')
	->setHtmlAttribute('class', 'big-number');

$form->addSelect('rank', 'Ordina per:', ['prezzo', 'nome'])
	->setHtmlAttribute('onchange', 'submit()'); // richiama la funzione JS submit() al momento della modifica


// Per impostare gli attributi dello stesso <form>
$form->setHtmlAttribute('id', 'myForm');
```

Specificare il tipo di elemento:

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

.[warning]
L'impostazione del tipo e degli altri attributi serve solo a fini visivi. La verifica della correttezza dell'input deve avvenire sul server, cosa che si può garantire scegliendo un [controllo di forma | controls] appropriato e specificando [le regole di convalida | validation].

Per i singoli elementi degli elenchi di radio o di caselle di controllo, possiamo impostare un attributo HTML con valori diversi per ciascuno di essi.
Notate i due punti dopo `style:`, che assicurano che il valore sia selezionato in base alla chiave:

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

Rende:

```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>
```

Per impostare attributi booleani, come `readonly`, si può usare la notazione con il punto interrogativo:

```php
$form->addCheckboxList('colors', 'Colors:', $colors)
	->setHtmlAttribute('readonly?', 'r'); // utilizzare un array per più chiavi, ad esempio ['r', 'g'].
```

Render:

```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>
```

Per le selectbox, il metodo `setHtmlAttribute()` imposta gli attributi dell'elemento `<select>` dell'elemento. Se si vogliono impostare gli attributi per ogni elemento
`<option>`utilizzeremo il metodo `setOptionAttribute()`. Inoltre, i due punti e il punto interrogativo usati sopra funzionano:

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

Rendering:

```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>
```


Prototipi .[#toc-prototypes]
----------------------------

Un modo alternativo per impostare gli attributi HTML è modificare il modello da cui viene generato l'elemento HTML. Il modello è un oggetto `Html` e viene restituito dal metodo `getControlPrototype()`:

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

Anche il modello di etichetta restituito da `getLabelPrototype()` può essere modificato in questo modo:

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

Per gli elementi Checkbox, CheckboxList e RadioList è possibile influenzare il modello di elemento che avvolge l'elemento. Viene restituito da `getContainerPrototype()`. Per impostazione predefinita è un elemento "vuoto", quindi non viene reso nulla, ma dandogli un nome verrà reso:

```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>
```

Nel caso di CheckboxList e RadioList è anche possibile influenzare il modello di separatore di elementi restituito dal metodo `getSeparatorPrototype()`. Per impostazione predefinita, è un elemento `<br>`. Se lo si cambia in un elemento coppia, avvolgerà i singoli elementi invece di separarli.
È anche possibile influenzare il modello di elemento HTML delle etichette degli elementi, che restituisce `getItemLabelPrototype()`.


Tradurre .[#toc-translating]
============================

Se state programmando un'applicazione multilingue, probabilmente avrete bisogno di rendere il modulo in diverse lingue. Il framework Nette definisce un'interfaccia di traduzione per questo scopo [api:Nette\Localization\Translator]. Non esiste un'implementazione predefinita in Nette, ma potete scegliere in base alle vostre esigenze tra diverse soluzioni già pronte che potete trovare su [Componette |https://componette.org/search/localization]. La loro documentazione spiega come configurare il traduttore.

Il modulo supporta l'output di testo attraverso il traduttore. Lo passiamo utilizzando il metodo `setTranslator()`:

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

D'ora in poi, non solo tutte le etichette, ma anche tutti i messaggi di errore o le voci delle caselle di selezione saranno tradotti in un'altra lingua.

È possibile impostare un traduttore diverso per i singoli elementi del modulo o disabilitare completamente la traduzione con `null`:

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

Per le [regole di convalida |validation], vengono passati al traduttore anche parametri specifici, ad esempio per la regola:

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

il traduttore viene chiamato con i seguenti parametri:

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

e quindi può scegliere la forma plurale corretta per la parola `characters` dal conteggio.


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

Poco prima che il form venga reso, possiamo invocare il nostro codice. Questo può, per esempio, aggiungere classi HTML agli elementi del modulo per una corretta visualizzazione. Aggiungiamo il codice all'array `onRender`:

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