Tag di Latte

Panoramica e descrizione di tutti i tag disponibili per impostazione predefinita nel sistema di template Latte.

Stampa

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

In Latte il tag {=...} serve a stampare qualsiasi espressione nell'output. Latte tiene alla vostra comodità, quindi se l'espressione inizia con una variabile o con una chiamata di funzione non serve scrivere il segno di uguale. In pratica, quindi, non serve quasi mai:

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

Come espressione potete scrivere tutto ciò che conoscete da PHP. Non dovete semplicemente imparare un nuovo linguaggio. Per esempio:

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

Vi preghiamo di non cercare un senso nell'esempio precedente, ma se lo trovate, fatecelo sapere :-)

Escaping dell'output

Qual è il compito più importante di un sistema di template? Impedire le vulnerabilità di sicurezza. Ed è esattamente ciò che Latte fa ogni volta che stampate qualcosa: ne esegue automaticamente l'escaping.

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

Per la precisione, Latte usa l'escaping sensibile al contesto, una funzionalità così importante e unica che le abbiamo dedicato un capitolo a parte.

E se state stampando contenuto codificato in HTML proveniente da una fonte attendibile? Allora potete disattivare facilmente l'escaping:

{$trustedHtmlString|noescape}

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

Stampare in JavaScript

Grazie all'escaping sensibile al contesto è meravigliosamente semplice stampare variabili dentro JavaScript: Latte si occupa dell'escaping corretto.

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

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

Genera:

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

Ecco anche perché non dovete scrivere gli apici attorno alla variabile: per le stringhe li aggiunge Latte automaticamente. E se volete inserire una variabile stringa dentro un'altra stringa, concatenatele semplicemente:

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

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

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

Filtri

L'espressione stampata si può modificare con i filtri. Per esempio, questo converte la stringa in maiuscolo e la accorcia a un massimo di 30 caratteri:

{$string|upper|truncate:30}

Potete applicare i filtri anche a parti di un'espressione, così:

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

Condizioni

{if} {elseif} {else}

Le condizioni si comportano esattamente come le loro controparti in PHP. Potete usare 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 di tipo pari, anche la coppia {if} ... {/if} si può scrivere con un n:attributo, per esempio:

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

Sapevate che agli n:attributi si può aggiungere il prefisso tag-? La condizione riguarderà allora solo la stampa dei tag HTML, mentre il contenuto tra di essi verrà stampato sempre:

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

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

Fantastico.

n:else n:elseif

Se scrivete la condizione {if} ... {/if} sotto forma di n:attributo, avete la possibilità di indicare rami alternativi con n:else (dalla 3.0.12) e n:elseif (dalla 3.1):

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

<em n:elseif="$count < 0">Conteggio non valido</em>

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

L'attributo n:else si può usare anche insieme a n:ifset, n:foreach, n:try, n:ifcontent e n:ifchanged.

{/if $cond}

Vi sorprenderà che l'espressione della condizione {if} si possa indicare anche nel tag di chiusura. È utile nelle situazioni in cui, aprendo la condizione, non ne conosciamo ancora il valore. Chiamiamola decisione differita.

Per esempio iniziamo a stampare una tabella con i record del database e solo a output terminato ci accorgiamo che nel database non c'era nessun record. Mettiamo quindi la condizione nel tag di chiusura {/if} e, se non ci sono record, non verrà stampato nulla:

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

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

Comodo, vero?

Nella condizione differita potete usare anche {else}, ma non {elseif}.

{ifset} {elseifset}

Vedi anche {ifset block}

Usate la condizione {ifset $var} per stabilire se una variabile (o più variabili) esiste e ha un valore diverso da null. È in realtà la stessa cosa di if (isset($var)) in PHP. Come ogni tag di tipo pari si può scrivere anche con un n:attributo, quindi mostriamo un esempio:

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

{ifchanged}

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

Se nel tag indichiamo una o più variabili, controlla se qualcuna di esse è cambiata e stampa di conseguenza il contenuto. Per esempio, l'esempio seguente stampa come intestazione la prima lettera di un nome ogni volta che cambia durante l'elenco dei nomi:

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

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

Se però non viene indicato alcun argomento, viene confrontato con il suo stato precedente il contenuto disegnato stesso. Nell'esempio precedente possiamo quindi tranquillamente omettere l'argomento nel tag. E naturalmente possiamo usare anche un n:attributo:

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

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

Dentro {ifchanged} si può usare anche una clausola {else}.

{switch} {case} {default}

Confronta un valore con più opzioni. È simile all'istruzione switch nota da PHP. Latte però la migliora:

• usa il confronto rigoroso (===)
• non richiede break

Si avvicina quindi molto alla struttura match introdotta in 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 articolo</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}

Il ciclo si scrive esattamente come in PHP:

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

Ha inoltre alcune comode funzionalità di cui parleremo ora.

Per esempio Latte controlla che le variabili create non sovrascrivano per sbaglio variabili globali con lo stesso nome. Questo vi salva dalle situazioni in cui vi aspettate che $lang contenga la lingua corrente della pagina e non vi accorgete che foreach $langs as $lang ha sovrascritto quella variabile.

Il ciclo foreach si può scrivere anche in modo molto elegante ed essenziale con un n:attributo:

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

Sapevate che agli n:attributi si può aggiungere il prefisso inner-? In tal caso nel ciclo verrà ripetuta solo la parte interna dell'elemento:

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

Stampa quindi qualcosa come:

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

{else}

Dentro il ciclo foreach potete indicare una clausola {else}, il cui contenuto viene mostrato se il ciclo è vuoto:

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

$iterator

Dentro il ciclo foreach Latte crea la variabile $iterator, che ci permette di conoscere informazioni utili sul ciclo in corso:

• $iterator->first – è questa la prima iterazione?
• $iterator->last – è questa l'ultima iterazione?
• $iterator->counter – contatore delle iterazioni, a partire da uno
• $iterator->counter0 – contatore delle iterazioni, a partire da zero
• $iterator->odd – è questa un'iterazione dispari?
• $iterator->even – è questa un'iterazione pari?
• $iterator->parent – l'iteratore che racchiude quello corrente
• $iterator->nextValue – l'elemento successivo del ciclo
• $iterator->nextKey – la chiave dell'elemento successivo del 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 è furbo e $iterator->last funziona non solo con gli array, ma anche quando il ciclo scorre un iteratore generico di cui non si conosce in anticipo il numero di elementi.

{first} {last} {sep}

Questi tag si possono usare dentro il ciclo {foreach}. Il contenuto di {first} viene disegnato se è la prima iterazione. Il contenuto di {last} viene disegnato… indovinate un po'? Sì, se è l'ultima iterazione. Sono in realtà scorciatoie per {if $iterator->first} e {if $iterator->last}.

I tag si possono usare elegantemente anche come n:attributi:

{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 disegnato se l'iterazione non è l'ultima, il che lo rende adatto a disegnare separatori, per esempio le virgole tra gli elementi elencati:

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

Piuttosto pratico, no?

{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. Leggete le istruzioni dettagliate.

Può sostituire elegantemente anche {first} e {last} nell'esempio qui 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}

Il ciclo si scrive esattamente come in PHP:

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

Il tag si può scrivere anche come n:attributo:

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

{while}

Anche qui il ciclo si scrive esattamente come in PHP:

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

Oppure 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 di PHP:

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

{continueIf} {skipIf} {breakIf}

I tag speciali {continueIf ?} e {breakIf ?} si possono usare per controllare qualsiasi ciclo. Se la condizione è soddisfatta, passano rispettivamente all'iterazione successiva o terminano il ciclo:

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

Il tag {skipIf} è molto simile a {continueIf}, ma non incrementa $iterator->counter. Questo evita i buchi nella numerazione quando si stampa il contatore e si saltano alcuni elementi. Inoltre, se tutti gli elementi vengono saltati, viene disegnata la clausola {else}.

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

{exitIf}

Termina il rendering di un template o di un blocco quando la condizione è soddisfatta (cioè “uscita anticipata”).

{exitIf !$messages}

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

Inclusione di template

{include 'file.latte'}

Vedi anche {include block} e {embed}

Il tag {include} carica e disegna il template indicato. Nel nostro amato linguaggio PHP è qualcosa come:

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

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

Al template incluso potete passare delle variabili così:

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

L'esistenza di un template si può verificare con la funzione hasTemplate().

Il contenuto incluso si può modificare con i filtri. L'esempio seguente rimuove tutto l'HTML e sistema maiuscole e minuscole:

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

Per impostazione predefinita l'ereditarietà dei template non entra in gioco. Potete usare i blocchi nei template inclusi, ma non sostituiranno i blocchi corrispondenti del template in cui vengono inclusi. Considerate i template inclusi come parti indipendenti e schermate di pagine o di moduli. Questo comportamento si può cambiare con il modificatore with blocks:

{include 'template.latte' with blocks}

Il rapporto tra il nome del file indicato nel tag e il file su disco dipende dal loader.

{sandbox}

Quando includete un template creato da un utente finale, dovreste valutare di metterlo in sandbox (maggiori informazioni nella documentazione della sandbox):

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

{block}

Vedi anche {block name}

I blocchi senza nome offrono la possibilità di applicare dei filtri a una parte del template. Per esempio potete applicare il filtro spaceless per rimuovere gli spazi superflui:

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

Gestione delle eccezioni

{try}

Grazie a questo tag è estremamente semplice creare template solidi.

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

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

Il contenuto della clausola facoltativa {else} viene disegnato solo quando si verifica un'eccezione:

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

Il tag si può scrivere anche come n:attributo:

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

È possibile anche definire un gestore di eccezioni personalizzato, per esempio a scopo di logging.

{rollback}

Il blocco {try} si può anche interrompere e saltare manualmente con {rollback}. Così non dovete controllare in anticipo tutti i dati in ingresso e potete decidere solo durante il rendering che l'oggetto non va disegnato affatto:

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

Variabili

{var} {default}

Nel template creiamo nuove variabili 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 le variabili solo se non esistono. Se una variabile esiste già e contiene il valore null, non verrà sovrascritta:

{default $lang = 'en'}

Potete indicare anche i tipi delle variabili. Per ora hanno valore informativo e Latte non li verifica.

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

{parameters}

Proprio come una funzione dichiara i suoi parametri, 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 indicato hanno automaticamente il valore predefinito null. I tipi dichiarati hanno per ora valore informativo e Latte non li verifica.

Le variabili diverse da quelle dichiarate non vengono passate al template. In questo il tag differisce da {default}.

{capture}

Cattura l'output in una variabile:

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

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

Come ogni tag di tipo pari, anche questo si può scrivere come n:attributo:

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

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

Altri

{contentType}

Usate questo tag per indicare il tipo di contenuto che il template rappresenta. Le possibilità sono:

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

Il suo uso è importante, perché imposta l'escaping sensibile al contesto e solo così Latte può eseguire correttamente l'escaping. Per esempio {contentType xml} passa alla modalità XML, {contentType text} disattiva del tutto l'escaping.

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

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

{debugbreak}

Indica un punto in cui l'esecuzione del programma verrà messa in pausa. Serve al debugging e permette al programmatore di esaminare l'ambiente di esecuzione e di verificare che il codice si comporti come previsto. Supporta Xdebug. Potete aggiungere anche una condizione che stabilisce quando il programma deve fermarsi.

{debugbreak}                {* mette in pausa il programma *}

{debugbreak $counter == 1}  {* mette in pausa il programma se la condizione è soddisfatta *}

{do}

Esegue del 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}

Scarica una variabile o il contesto corrente.

{dump $name} {* scarica la variabile $name *}

{dump}       {* scarica tutte le variabili attualmente definite *}

Richiede la libreria Tracy.

{php}

Per impostazione predefinita {php} funziona come alias obsoleto di {do} e valuta solo una singola espressione. Per eseguire codice PHP qualsiasi, il tag va attivato con l'estensione RawPhpExtension.

{spaceless}

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

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

Genera:

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

Il tag si può scrivere anche come n:attributo.

{syntax}

I tag di Latte non devono per forza essere racchiusi tra singole parentesi graffe. Potete scegliere un altro separatore, anche in fase di esecuzione. Lo si fa con {syntax …}, dove il parametro può essere:

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

Con gli n:attributi potete disattivare Latte anche solo per un blocco di JavaScript, per esempio:

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

Latte si può usare in modo molto comodo dentro JavaScript: basta evitare costrutti come quelli di questo esempio, in cui una lettera segue immediatamente {, vedi Latte dentro JavaScript o CSS.

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

{trace}

Solleva un'eccezione Latte\RuntimeException, il cui stack trace segue lo spirito dei template. Al posto delle chiamate a funzioni e metodi contiene cioè le chiamate ai blocchi e le inclusioni di template. Se usate uno strumento per mostrare chiaramente le eccezioni sollevate, come Tracy, vedrete con chiarezza lo stack delle chiamate, compresi tutti gli argomenti passati.

Aiuti per chi scrive HTML

n:class

Da Latte 3.1 l'attributo HTML class standard ha acquisito le stesse funzionalità. Non avete quindi più bisogno di usare n:class.

Grazie a n:class è molto semplice generare l'attributo HTML class esattamente come serve.

Esempio: mi serve che l'elemento attivo abbia la classe active:

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

E poi mi serve 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 che tutti gli elementi abbiano la classe list-item:

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

Straordinariamente semplice, no?

n:attr

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

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

A seconda dei valori restituiti stampa, per esempio:

<input type="checkbox">

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

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

Anche le funzionalità degli attributi intelligenti di Latte 3.1, come l'eliminazione dei valori null o il passaggio di array a class o style, funzionano dentro n:attr:

<div n:attr="class: [a, b], title: $title"></div>

n:tag

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

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

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

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

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

n:ifcontent

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

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

A seconda del valore della variabile $error stamperà:

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

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

Traduzione

Perché i tag di traduzione funzionino, dovete attivare il traduttore. Per la traduzione potete usare anche il filtro translate.

{_...}

Traduce i valori in altre lingue.

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

Al traduttore si possono 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 si può scrivere anche come n:attributo, per tradurre l'interno dell'elemento:

<h1 n:translate>Ordine</h1>