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

Il sistema di template 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 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.

`{control}`

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

{control signInForm}

L'aspetto del modulo renderizzato può essere modificato configurando il Renderer e i singoli controlli.

`n:name`

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

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

<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()):

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

{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}:

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

{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:

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

<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

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.

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

{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, per cui è possibile inserire il nome dell'elemento da disegnare. Ad esempio:

...
	{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}:

{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 come un blocco, compreso il parametro $form:

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

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

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

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

{import basic-form.latte}

Casi speciali

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:

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

<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

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

$form->render();

L'aspetto del modulo renderizzato può essere modificato configurando il Renderer e i singoli controlli.

Rendering manuale

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:

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

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

È 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 Nette\Forms\Rendering\DefaultFormRenderer. Questo renderà gli elementi del modulo come una tabella HTML. L'output appare come questo:

<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 appropriati. Il primo indice rappresenta sempre un'area e il secondo un elemento. Tutte le rispettive aree sono mostrate nell'immagine:

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

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

<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

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:

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

Se si vuole inserire del contenuto HTML, si usa la classe Html.

use Nette\Utils\Html;

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

L'elemento Html può essere utilizzato anche al posto di label: $form->addCheckbox('conditions', $label).

Raggruppare gli input

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

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

$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

È possibile trovare esempi di configurazione del Renderer per Twitter Bootstrap 2, Bootstrap 3 e Bootstrap 4

Attributi HTML

È possibile impostare qualsiasi attributo HTML ai controlli dei moduli utilizzando setHtmlAttribute(string $name, $value = true):

$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


// applicazione su <form>
$form->setHtmlAttribute('id', 'myForm');

Impostazione del tipo di input:

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

È possibile impostare l'attributo HTML per le singole voci degli elenchi di radio o di caselle di controllo con valori diversi per ciascuna di esse. Notate i due punti dopo style: per garantire che il valore sia selezionato per chiave:

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

Rende:

<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 un attributo HTML logico (che non ha valore, come readonly), si può usare un punto interrogativo:

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

Render:

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

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

Rendering:

<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

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():

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

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

$input = $form->addCheckbox('send');
echo $input->getControl();
// <label><input type="checkbox" name="send"></label>

$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

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 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. La loro documentazione spiega come configurare il traduttore.

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

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

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

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

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

$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

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:

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

Rendering dei moduli

Rendering con Latte

{control}

n:name

{label} {input}

{inputError}

{form}

Rendering automatico

Casi speciali

Rendering senza Latte

Rendering manuale

Renderer

Opzioni

Raggruppare gli input

Supporto Bootstrap

Attributi HTML

Prototipi

Tradurre

Evento onRender

`{control}`

`n:name`

`{label}` `{input}`

`{inputError}`

`{form}`