Tag Latte

Panoramica e descrizione di tutti i tag del sistema di templating Latte, disponibili di default.

Stampa

{$var} {...} {=...}

In Latte, si utilizza il tag {=...} per stampare qualsiasi espressione nell'output. Latte tiene alla vostra comodità, quindi se l'espressione inizia con una variabile o una chiamata di funzione, non è necessario scrivere il segno di uguale. Il che in pratica significa che non è quasi mai necessario scriverlo:

Nome: {$name} {$surname}<br>
Età: {date('Y') - $birth}<br>

Come espressione potete scrivere qualsiasi cosa conosciate da PHP. Semplicemente non dovete imparare un nuovo linguaggio. Ad esempio:

{='0' . ($num ?? $num * 3) . ', ' . PHP_VERSION}

Per favore, non cercate alcun significato nell'esempio precedente, ma se ne trovate uno, scriveteci :-)

Escaping dell'output

Qual è il compito più importante di un sistema di templating? Prevenire le falle di sicurezza. Ed è esattamente quello che fa Latte ogni volta che stampate qualcosa. Esegue automaticamente l'escaping:

<p>{='one < two'}</p>   {* stampa: '<p>one &lt; two</p>' *}

Per essere precisi, Latte utilizza l'escaping sensibile al contesto, una caratteristica così importante e unica che le abbiamo dedicato un capitolo separato.

E cosa succede se stampate contenuto codificato in HTML da una fonte attendibile? Allora potete facilmente disabilitare l'escaping:

{$trustedHtmlString|noescape}

L'uso improprio del filtro noescape può portare a una vulnerabilità XSS! Non utilizzatelo mai a meno che non siate assolutamente sicuri di quello che state facendo e che la stringa stampata provenga da una fonte attendibile.

Stampa in JavaScript

Grazie all'escaping sensibile al contesto, è incredibilmente facile stampare variabili all'interno di JavaScript, e Latte si occupa del corretto escaping.

La variabile non deve essere solo una stringa, è supportato qualsiasi tipo di dato, che viene poi codificato come JSON:

{var $foo = ['hello', true, 1]}
<script>
	alert({$foo});
</script>

Genera:

<script>
	alert(["hello", true, 1]);
</script>

Questo è anche il motivo per cui non si scrivono virgolette attorno alla variabile: Latte le aggiunge automaticamente per le stringhe. E se voleste inserire una variabile stringa in un'altra stringa, semplicemente concatenatele:

<script>
	alert('Hello ' + {$name} + '!');  // OK

	alert({="Hello $name!"});         // OK

	alert('Hello {$name} !');         // ERRORE!
</script>

Filtri

L'espressione stampata può essere modificata da un filtro. Ad esempio, così convertiamo una stringa in maiuscolo e la accorciamo a un massimo di 30 caratteri:

{$string|upper|truncate:30}

Potete applicare i filtri anche a parti parziali dell'espressione in questo modo:

{$left . ($middle|upper) . $right}

Condizioni

{if} {elseif} {else}

Le condizioni si comportano allo stesso modo delle loro controparti in PHP. Potete utilizzare al loro interno le stesse espressioni che conoscete da PHP, non dovete imparare un nuovo linguaggio.

{if $product->inStock > Stock::Minimum}
	Disponibile
{elseif $product->isOnWay()}
	In arrivo
{else}
	Non disponibile
{/if}

Come ogni tag accoppiato, anche la coppia {if} ... {/if} può essere scritta sotto forma di n:attributo, ad esempio:

<p n:if="$count > 0">Disponibili {$count} pezzi</p>

Sapete che agli n:attributi potete aggiungere il prefisso tag-? Allora la condizione si applicherà solo alla stampa dei tag HTML e il contenuto tra di essi verrà sempre stampato:

<a href="..." n:tag-if="$clickable">Hello</a>

{* stampa 'Hello' quando $clickable è falso *}
{* stampa '<a href="...">Hello</a>' quando $clickable è vero *}

Fantastico.

n:else

Se scrivete la condizione {if} ... {/if} sotto forma di n:attributo, avete la possibilità di indicare anche un ramo alternativo usando n:else:

<strong n:if="$count > 0">Disponibili {$count} pezzi</strong>

<em n:else>non disponibile</em>

L'attributo n:else può essere utilizzato anche in coppia con n:ifset, n:foreach, n:try, n:ifcontent e n:ifchanged.

{/if $cond}

Potreste essere sorpresi che l'espressione nella condizione {if} possa essere specificata anche nel tag di chiusura. Questo è utile in situazioni in cui, all'apertura della condizione, non conosciamo ancora il suo valore. Chiamiamola decisione posticipata.

Ad esempio, iniziamo a stampare una tabella con record da un database e solo dopo aver completato la stampa ci rendiamo conto che non c'era alcun record nel database. Quindi mettiamo una condizione su questo nel tag di chiusura {/if} e se non ci sono record, non verrà stampato nulla:

{if}
	<h1>Elenco righe dal database</h1>

	<table>
	{foreach $resultSet as $row}
		...
	{/foreach}
	</table>
{/if isset($row)}

Comodo, vero?

Nella condizione posticipata si può usare anche {else}, ma non {elseif}.

{ifset} {elseifset}

Vedi anche {ifset block}

Usando la condizione {ifset $var} verifichiamo se una variabile (o più variabili) esiste e ha un valore non null. In pratica, è la stessa cosa di if (isset($var)) in PHP. Come ogni tag accoppiato, può essere scritto anche sotto forma di n:attributo, quindi vediamolo come esempio:

<meta name="robots" content={$robots} n:ifset="$robots">

{ifchanged}

{ifchanged} controlla se il valore di una variabile è cambiato dall'ultima iterazione nel ciclo (foreach, for o while).

Se nel tag specifichiamo una o più variabili, controllerà se qualcuna di esse è cambiata e stamperà il contenuto di conseguenza. Ad esempio, l'esempio seguente stamperà la prima lettera del nome come titolo ogni volta che cambia durante la stampa dei nomi:

{foreach ($names|sort) as $name}
	{ifchanged $name[0]} <h2>{$name[0]}</h2> {/ifchanged}

	<p>{$name}</p>
{/foreach}

Tuttavia, se non specifichiamo alcun argomento, verrà controllato il contenuto renderizzato rispetto al suo stato precedente. Ciò significa che nell'esempio precedente possiamo tranquillamente omettere l'argomento nel tag. E ovviamente possiamo anche usare un n:attributo:

{foreach ($names|sort) as $name}
	<h2 n:ifchanged>{$name[0]}</h2>

	<p>{$name}</p>
{/foreach}

All'interno di {ifchanged} è possibile specificare anche la clausola {else}.

{switch} {case} {default}

Confronta un valore con più opzioni. È un analogo dell'istruzione condizionale switch che conoscete da PHP. Tuttavia, Latte la migliora:

• utilizza un confronto rigoroso (===)
• non necessita di break

È quindi l'esatto equivalente della struttura match introdotta con PHP 8.0.

{switch $transport}
	{case train}
		In treno
	{case plane}
		In aereo
	{default}
		Altrimenti
{/switch}

La clausola {case} può contenere più valori separati da virgole:

{switch $status}
{case $status::New}<b>nuovo elemento</b>
{case $status::Sold, $status::Unknown}<i>non disponibile</i>
{/switch}

Cicli

In Latte trovate tutti i cicli che conoscete da PHP: foreach, for e while.

{foreach}

Scriviamo il ciclo esattamente come in PHP:

{foreach $langs as $code => $lang}
	<span>{$lang}</span>
{/foreach}

Inoltre, ha alcune comode funzionalità di cui parleremo ora.

Ad esempio, Latte controlla se le variabili create sovrascrivono accidentalmente variabili globali con lo stesso nome. Questo salva situazioni in cui vi aspettate che $lang contenga la lingua corrente della pagina e non vi rendete conto che foreach $langs as $lang vi ha sovrascritto quella variabile.

Il ciclo foreach può anche essere scritto in modo molto elegante e conciso usando un n:attributo:

<ul>
	<li n:foreach="$items as $item">{$item->name}</li>
</ul>

Sapete che agli n:attributi potete aggiungere il prefisso inner-? Allora solo l'interno dell'elemento verrà ripetuto nel ciclo:

<div n:inner-foreach="$items as $item">
	<h4>{$item->title}</h4>
	<p>{$item->description}</p>
</div>

Quindi verrà stampato qualcosa come:

<div>
	<h4>Foo</h4>
	<p>Lorem ipsum.</p>
	<h4>Bar</h4>
	<p>Sit dolor.</p>
</div>

{else}

All'interno del ciclo foreach è possibile specificare la clausola {else}, il cui contenuto viene visualizzato se il ciclo è vuoto:

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Siamo spiacenti, non ci sono utenti in questo elenco</em></li>
	{/foreach}
</ul>

$iterator

All'interno del ciclo foreach, Latte crea la variabile $iterator, tramite la quale possiamo ottenere informazioni utili sul ciclo in corso:

• $iterator->first – è la prima volta che si attraversa il ciclo?
• $iterator->last – è l'ultimo passaggio?
• $iterator->counter – qual è il numero del passaggio contando da uno?
• $iterator->counter0 – qual è il numero del passaggio contando da zero?
• $iterator->odd – è un passaggio dispari?
• $iterator->even – è un passaggio pari?
• $iterator->parent – l'iteratore che racchiude quello attuale
• $iterator->nextValue – l'elemento successivo nel ciclo
• $iterator->nextKey – la chiave dell'elemento successivo nel ciclo

{foreach $rows as $row}
	{if $iterator->first}<table>{/if}

	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>

	{if $iterator->last}</table>{/if}
{/foreach}

Latte è intelligente e $iterator->last funziona non solo con gli array, ma anche quando il ciclo viene eseguito su un iteratore generico, dove il numero di elementi non è noto in anticipo.

{first} {last} {sep}

Questi tag possono essere utilizzati all'interno del ciclo {foreach}. Il contenuto di {first} viene renderizzato se è il primo passaggio. Il contenuto di {last} viene renderizzato… indovinerete? Sì, se è l'ultimo passaggio. Sono in realtà scorciatoie per {if $iterator->first} e {if $iterator->last}.

I tag possono anche essere utilizzati elegantemente come n:attributo:

{foreach $rows as $row}
	{first}<h1>Elenco dei nomi</h1>{/first}

	<p>{$row->name}</p>

	<hr n:last>
{/foreach}

Il contenuto del tag {sep} viene renderizzato se il passaggio non è l'ultimo, quindi è utile per renderizzare separatori, ad esempio virgole tra gli elementi stampati:

{foreach $items as $item} {$item} {sep}, {/sep} {/foreach}

È piuttosto pratico, vero?

{iterateWhile}

Semplifica il raggruppamento di dati lineari durante l'iterazione in un ciclo foreach eseguendo l'iterazione in un ciclo annidato finché la condizione è soddisfatta. Leggi il tutorial dettagliato.

Può anche sostituire elegantemente {first} e {last} nell'esempio sopra:

{foreach $rows as $row}
	<table>

	{iterateWhile}
	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>
	{/iterateWhile true}

	</table>
{/foreach}

Vedi anche i filtri batch e group.

{for}

Scriviamo il ciclo esattamente come in PHP:

{for $i = 0; $i < 10; $i++}
	<span>Elemento {$i}</span>
{/for}

Il tag può essere utilizzato anche come n:attributo:

<h1 n:for="$i = 0; $i < 10; $i++">{$i}</h1>

{while}

Anche in questo caso, scriviamo il ciclo esattamente come in PHP:

{while $row = $result->fetch()}
	<span>{$row->title}</span>
{/while}

O come n:attributo:

<span n:while="$row = $result->fetch()">
	{$row->title}
</span>

È possibile anche una variante con la condizione nel tag di chiusura, che corrisponde al ciclo do-while in PHP:

{while}
	<span>{$item->title}</span>
{/while $item = $item->getNext()}

{continueIf} {skipIf} {breakIf}

Per controllare qualsiasi ciclo è possibile utilizzare i tag {continueIf ?} e {breakIf ?}, che passano all'elemento successivo rispettivamente terminano il ciclo se la condizione è soddisfatta:

{foreach $rows as $row}
	{continueIf $row->date < $now}
	{breakIf $row->parent === null}
	...
{/foreach}

Il tag {skipIf} è molto simile a {continueIf}, ma non incrementa il contatore $iterator->counter, quindi se lo stampiamo e allo stesso tempo saltiamo alcuni elementi, non ci saranno buchi nella numerazione. E anche la clausola {else} viene renderizzata se saltiamo tutti gli elementi.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>Siamo spiacenti, non ci sono adulti in questo elenco</em></li>
	{/foreach}
</ul>

{exitIf}

Termina il rendering del template o del blocco se la condizione è soddisfatta (il cosiddetto “early exit”).

{exitIf !$messages}

<h1>Messaggi</h1>
<div n:foreach="$messages as $message">
   {$message}
</div>

Inclusione di template

{include 'file.latte'}

Vedi anche {include block}

Il tag {include} carica e renderizza il template specificato. Se dovessimo parlare nel linguaggio del nostro linguaggio preferito PHP, sarebbe qualcosa come:

<?php include 'header.phtml'; ?>

I template inclusi non hanno accesso alle variabili del contesto attivo, hanno accesso solo alle variabili globali.

Potete passare variabili al template incluso in questo modo:

{include 'template.latte', foo: 'bar', id: 123}

Il nome del template può essere qualsiasi espressione PHP:

{include $someVar}
{include $ajax ? 'ajax.latte' : 'not-ajax.latte'}

Il contenuto incluso può essere modificato usando i filtri. L'esempio seguente rimuove tutto l'HTML e modifica la dimensione dei caratteri:

<title>{include 'heading.latte' |stripHtml|capitalize}</title>

Per impostazione predefinita, l'ereditarietà dei template non figura in alcun modo in questo caso. Anche se possiamo usare i blocchi nel template incluso, i blocchi corrispondenti nel template in cui viene incluso non verranno sostituiti. Pensate ai template inclusi come parti separate e isolate di pagine o moduli. Questo comportamento può essere modificato usando il modificatore with blocks:

{include 'template.latte' with blocks}

La relazione tra il nome del file specificato nel tag e il file sul disco è compito del loader.

{sandbox}

Quando si include un template creato dall'utente finale, si dovrebbe considerare la modalità sandbox (maggiori informazioni nella documentazione di sandbox):

{sandbox 'untrusted.latte', level: 3, data: $menu}

{block}

Vedi anche {block name}

I blocchi senza nome servono come modo per applicare i filtri a una parte del template. Ad esempio, così si può applicare il filtro strip, che rimuove gli spazi superflui:

{block|strip}
<ul>
	<li>Hello World</li>
</ul>
{/block}

Gestione delle eccezioni

{try}

Grazie a questo tag, è estremamente facile creare template robusti.

Se si verifica un'eccezione durante il rendering del blocco {try}, l'intero blocco viene scartato e il rendering continuerà dopo di esso:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
{/try}

Il contenuto nella clausola opzionale {else} viene renderizzato solo quando si verifica un'eccezione:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Siamo spiacenti, non è stato possibile caricare i tweet.</p>
{/try}

Il tag può essere utilizzato anche come n:attributo:

<ul n:try>
	...
</ul>

È anche possibile definire un gestore di eccezioni personalizzato, ad esempio per il logging.

{rollback}

Il blocco {try} può essere interrotto e saltato anche manually usando {rollback}. Grazie a ciò, non è necessario controllare in anticipo tutti i dati di input e solo durante il rendering si può decidere che non si desidera affatto renderizzare l'oggetto:

{try}
<ul>
	{foreach $people as $person}
 		{skipIf $person->age < 18}
 		<li>{$person->name}</li>
	{else}
		{rollback}
	{/foreach}
</ul>
{/try}

Variabili

{var} {default}

Creiamo nuove variabili nel template con il tag {var}:

{var $name = 'John Smith'}
{var $age = 27}

{* Dichiarazione multipla *}
{var $name = 'John Smith', $age = 27}

Il tag {default} funziona in modo simile, ma crea variabili solo se non esistono. Se la variabile esiste già e contiene il valore null, non verrà sovrascritta:

{default $lang = 'cs'}

Potete specificare anche i tipi delle variabili. Per ora sono informativi e Latte non li controlla.

{var string $name = $article->getTitle()}
{default int $id = 0}

{parameters}

Proprio come una funzione dichiara i suoi parametri, anche un template può dichiarare le sue variabili all'inizio:

{parameters
	$a,
	?int $b,
	int|string $c = 10
}

Le variabili $a e $b senza un valore predefinito specificato hanno automaticamente il valore predefinito null. I tipi dichiarati sono per ora informativi e Latte non li controlla.

Altre variabili diverse da quelle dichiarate non vengono trasferite al template. Questo le differenzia dal tag {default}.

{capture}

Cattura l'output in una variabile:

{capture $var}
<ul>
	<li>Hello World</li>
</ul>
{/capture}

<p>Catturato: {$var}</p>

Il tag può, come ogni tag accoppiato, essere scritto anche come n:attributo:

<ul n:capture="$var">
	<li>Hello World</li>
</ul>

L'output HTML viene salvato nella variabile $var sotto forma di oggetto Latte\Runtime\Html, per evitare l'escaping indesiderato durante la stampa.

Altri

{contentType}

Con questo tag specifichi quale tipo di contenuto rappresenta il template. Le opzioni sono:

• html (tipo predefinito)
• xml
• javascript
• css
• calendar (iCal)
• text

Il suo utilizzo è importante perché imposta l'escaping sensibile al contesto e solo così può eseguire l'escaping correttamente. Ad esempio, {contentType xml} passa alla modalità XML, {contentType text} disabilita completamente l'escaping.

Se il parametro è un tipo MIME completo, come ad esempio application/xml, invierà anche l'header HTTP Content-Type al browser:

{contentType application/xml}
<?xml version="1.0"?>
<rss version="2.0">
	<channel>
		<title>Feed RSS</title>
		<item>
			...
		</item>
	</channel>
</rss>

{debugbreak}

Indica il punto in cui l'esecuzione del programma verrà sospesa e verrà avviato il debugger, in modo che il programmatore possa ispezionare l'ambiente di runtime e verificare se il programma funziona come previsto. Supporta Xdebug. È possibile aggiungere una condizione che determina quando il programma deve essere sospeso.

{debugbreak}                {* sospende il programma *}

{debugbreak $counter == 1}  {* sospende il programma se la condizione è soddisfatta *}

{do}

Esegue codice PHP e non stampa nulla. Come per tutti gli altri tag, per codice PHP si intende una singola espressione, vedi limitazioni di PHP.

{do $num++}

{dump}

Esegue il dump di una variabile o del contesto corrente.

{dump $name} {* Esegue il dump della variabile $name *}

{dump}       {* Esegue il dump di tutte le variabili attualmente definite *}

Richiede la libreria Tracy.

{php}

Permette di eseguire qualsiasi codice PHP. Il tag deve essere attivato tramite l'estensione RawPhpExtension.

{spaceless}

Rimuove gli spazi bianchi superflui dall'output. Funziona in modo simile al filtro spaceless.

{spaceless}
	<ul>
		<li>Hello</li>
	</ul>
{/spaceless}

Genera

<ul> <li>Hello</li> </ul>

Il tag può anche essere scritto come n:attributo.

{syntax}

I tag Latte non devono essere delimitati solo da semplici parentesi graffe. Possiamo scegliere anche un altro delimitatore, e persino in fase di esecuzione. A questo serve {syntax …}, dove come parametro è possibile specificare:

• double: {{...}}
• off: disabilita completamente l'elaborazione dei tag Latte

Utilizzando gli n:attributi è possibile disabilitare Latte ad esempio solo per un blocco JavaScript:

<script n:syntax="off">
	var obj = {var: 123}; // questo non è più un tag
</script>

Latte può essere utilizzato molto comodamente anche all'interno di JavaScript, basta evitare costrutti come in questo esempio, dove una lettera segue immediatamente {, vedi Latte all'interno di JavaScript o CSS.

Se disabiliti Latte usando {syntax off} (cioè con il tag, non con l'n:attributo), ignorerà rigorosamente tutti i tag fino a {/syntax}

{trace}

Lancia un'eccezione Latte\RuntimeException, il cui stack trace è nello spirito dei template. Cioè, invece di chiamate a funzioni e metodi, contiene chiamate a blocchi e inclusioni di template. Se utilizzate uno strumento per la visualizzazione chiara delle eccezioni lanciate, come ad esempio Tracy, vedrete chiaramente lo stack delle chiamate inclusi tutti gli argomenti passati.

Aiutanti per il codificatore HTML

n:class

Grazie a n:class è molto facile generare l'attributo HTML class esattamente come desiderato.

Esempio: ho bisogno che l'elemento attivo abbia la classe active:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active">...</a>
{/foreach}

E inoltre, che il primo elemento abbia le classi first e main:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active, $iterator->first ? 'first main'">...</a>
{/foreach}

E tutti gli elementi devono avere la classe list-item:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active, $iterator->first ? 'first main', list-item">...</a>
{/foreach}

Incredibilmente semplice, vero?

n:attr

L'attributo n:attr sa generare qualsiasi attributo HTML con la stessa eleganza di n:class.

{foreach $data as $item}
	<input type="checkbox" n:attr="value: $item->getValue(), checked: $item->isActive()">
{/foreach}

A seconda dei valori restituiti, stamperà ad es.:

<input type="checkbox">

<input type="checkbox" value="Hello">

<input type="checkbox" value="Hello" checked>

n:tag

L'attributo n:tag sa cambiare dinamicamente il nome di un elemento HTML.

<h1 n:tag="$heading" class="main">{$title}</h1>

Se $heading === null, verrà stampato il tag <h1> senza modifiche. Altrimenti, il nome dell'elemento verrà cambiato nel valore della variabile, quindi per $heading === 'h3' verrà stampato:

<h3 class="main">...</h3>

Poiché Latte è un sistema di templating sicuro, controlla che il nuovo nome del tag sia valido e non contenga valori indesiderati o dannosi.

n:ifcontent

Impedisce che venga stampato un elemento HTML vuoto, cioè un elemento che non contiene nulla tranne spazi bianchi.

<div>
	<div class="error" n:ifcontent>{$error}</div>
</div>

Stampa a seconda del valore della variabile $error:

{* $error = '' *}
<div>
</div>

{* $error = 'Required' *}
<div>
	<div class="error">Required</div>
</div>

Traduzioni

Affinché i tag per la traduzione funzionino, è necessario attivare il traduttore. Per la traduzione potete anche utilizzare il filtro translate.

{_...}

Traduce i valori in altre lingue.

<a href="basket">{_'Carrello'}</a>
<span>{_$item}</span>

Al traduttore è possibile passare anche altri parametri:

<a href="basket">{_'Carrello', domain: order}</a>

{translate}

Traduce parti del template:

<h1>{translate}Ordine{/translate}</h1>

{translate domain: order}Lorem ipsum ...{/translate}

Il tag può anche essere scritto come n:attributo, per tradurre l'interno dell'elemento:

<h1 n:translate>Ordine</h1>