Etichette per il latte

Riepilogo e descrizione di tutti i tag incorporati di Latte.

Stampa

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

Latte utilizza il tag {=...} per stampare qualsiasi espressione in uscita. Se l'espressione inizia con una variabile o una chiamata di funzione, non è necessario scrivere il segno di uguale. In pratica, ciò significa che non è quasi mai necessario scriverlo:

Name: {$name} {$surname}<br>
Age: {date('Y') - $birth}<br>

È possibile scrivere qualsiasi cosa si conosca di PHP come espressione. Non è necessario imparare un nuovo linguaggio. Per esempio:

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

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

Uscita in fuga

Qual è il compito più importante di un sistema di template? Evitare le falle di sicurezza. Ed è proprio questo che Latte fa ogni volta che si stampa qualcosa in output. Esegue automaticamente l'escape di tutto:

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

Per essere precisi, Latte utilizza l'escape sensibile al contesto, una caratteristica talmente importante e unica che le abbiamo dedicato un capitolo a parte.

E se stampate contenuti codificati in HTML da una fonte affidabile? Allora potete facilmente disattivare l'escape:

{$trustedHtmlString|noescape}

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

Stampa in JavaScript

Grazie all'escape sensibile al contesto, è molto facile stampare le variabili all'interno di JavaScript e Latte le metterà correttamente in escape.

La variabile non deve essere necessariamente 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 mettere le variabili tra virgolette: Latte le aggiunge intorno alle stringhe. E se si vuole inserire una variabile stringa in un'altra stringa, basta concatenarle:

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

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

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

Filtri

L'espressione stampata può essere modificata da filtri. Ad esempio, questo esempio converte la stringa in maiuscolo e la accorcia a un massimo di 30 caratteri:

{$string|upper|truncate:30}

È inoltre possibile applicare filtri a parti di un'espressione come segue:

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

Condizioni

{if} {elseif} {else}

Le condizioni si comportano allo stesso modo delle loro controparti PHP. È possibile utilizzare le stesse espressioni conosciute in PHP, senza dover imparare un nuovo linguaggio.

{if $product->inStock > Stock::Minimum}
	In stock
{elseif $product->isOnWay()}
	On the way
{else}
	Not available
{/if}

Come qualsiasi tag di coppia, una coppia di {if} ... {/ if} può essere scritta come n:attributo, ad esempio:

<p n:if="$count > 0">In stock {$count} items</p>

Sapete che è possibile aggiungere il prefisso tag- a n:attributi? In questo modo la condizione riguarderà solo i tag HTML e il contenuto tra di essi verrà sempre stampato:

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

{* prints 'Hello' when $clickable is falsey *}
{* prints '<a href="...">Hello</a>' when $clickable is truthy *}

Bello.

n:else

Se si scrive la condizione {if} ... {/if} sotto forma di un attributo n:, si ha la possibilità di specificare un ramo alternativo usando n:else:

<strong n:if="$count > 0">In stock {$count} items</strong>

<em n:else>not available</em>

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

{/if $cond}

Potreste essere sorpresi dal fatto che l'espressione della condizione {if} può essere specificata anche nel tag finale. Questo è utile in situazioni in cui non si conosce ancora il valore della condizione quando il tag viene aperto. Chiamiamola decisione differita.

Ad esempio, iniziamo a elencare una tabella con i record del database e solo dopo aver completato il report ci rendiamo conto che non c'era nessun record nel database. Quindi inseriamo la condizione nel tag finale {/if} e se non c'è nessun record, non verrà stampato nulla:

{if}
	<h1>Printing rows from the database</h1>

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

Comodo, vero?

Si può usare anche {else} nella condizione differita, ma non {elseif}.

{ifset} {elseifset}

Vedi anche {ifset block}

Utilizzare la condizione {ifset $var} per determinare se una variabile (o più variabili) esiste e ha un valore non nullo. In realtà è la stessa cosa di if (isset($var)) in PHP. Come ogni tag di coppia, può essere scritto nella forma n:attribute, quindi lo mostriamo in un esempio:

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

{ifchanged}

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

Se si specificano una o più variabili nel tag, questo controlla se una di esse è cambiata e stampa il contenuto di conseguenza. Ad esempio, l'esempio seguente stampa la prima lettera di un nome come titolo ogni volta che cambia nell'elenco dei nomi:

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

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

Tuttavia, se non viene fornito alcun argomento, il contenuto reso viene controllato rispetto al suo stato precedente. Ciò significa che nell'esempio precedente si può tranquillamente omettere l'argomento nel tag. Naturalmente, possiamo anche usare n:attribute:

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

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

Si può anche includere una clausola {else} all'interno del tag {ifchanged}.

{switch} {case} {default}

Confronta il valore con più opzioni. È simile alla struttura switch, conosciuta in PHP. Tuttavia, Latte la migliora:

• utilizza un confronto rigoroso (===)
• non ha bisogno di un elemento break

Quindi è l'esatto equivalente della struttura match di cui PHP 8.0 è dotato.

{switch $transport}
	{case train}
		By train
	{case plane}
		By plane
	{default}
		Differently
{/switch}

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

{switch $status}
{case $status::New}<b>new item</b>
{case $status::Sold, $status::Unknown}<i>not available</i>
{/switch}

Cicli

In Latte sono disponibili tutti i cicli conosciuti in PHP: foreach, for e while.

{foreach}

Si scrive il ciclo esattamente come in PHP:

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

Inoltre, ha alcune utili modifiche di cui parleremo ora.

Per esempio, Latte controlla che le variabili create non sovrascrivano accidentalmente le variabili globali con lo stesso nome. Questo vi salverà quando assumete che $lang sia la lingua corrente della pagina e non vi rendete conto che foreach $langs as $lang ha sovrascritto quella variabile.

Anche il ciclo foreach può essere scritto in modo molto elegante ed economico con n:attribute:

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

Sapevate che potete anteporre il prefisso inner- a n:attribute? In questo modo, solo la parte interna dell'elemento verrà ripetuta nel ciclo:

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

Quindi viene stampato qualcosa come:

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

{else}

Il ciclo foreach può contenere una clausola opzionale {else} il cui testo viene visualizzato se l'array dato è vuoto:

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Sorry, no users in this list</em></li>
	{/foreach}
</ul>

$iterator

All'interno del ciclo foreach viene inizializzata la variabile $iterator. Essa contiene informazioni importanti sul ciclo corrente.

• $iterator->first – è la prima iterazione?
• $iterator->last – è l'ultima iterazione?
• $iterator->counter – contatore di iterazioni, parte da 1
• $iterator->counter0 – contatore di iterazioni, parte da 0
• $iterator->odd – questa iterazione è dispari?
• $iterator->even – questa iterazione è pari?
• $iterator->parent – l'iteratore che circonda quello attuale
• $iterator->nextValue – il prossimo elemento del ciclo
• $iterator->nextKey – la chiave del prossimo elemento 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}

Il latte è intelligente e $iterator->last funziona non solo per gli array, ma anche quando il ciclo scorre su un iteratore generico in cui 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 reso per il primo passaggio. Il contenuto di {last} viene reso… indovinate? Sì, per l'ultimo passaggio. Si tratta in realtà di scorciatoie per {if $iterator->first} e {if $iterator->last}.

I tag possono anche essere scritti come n:attributes:

{foreach $rows as $row}
	{first}<h1>List of names</h1>{/first}

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

	<hr n:last>
{/foreach}

Il contenuto di {sep} viene reso se l'iterazione non è l'ultima, quindi è adatto alla stampa di delimitatori, come le virgole tra gli elementi elencati:

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

È piuttosto pratico, vero?

{iterateWhile}

Semplifica il raggruppamento dei dati lineari durante l'iterazione in un ciclo foreach, iterando in un ciclo annidato finché non viene soddisfatta una condizione. Leggete le istruzioni dettagliate.

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

{foreach $rows as $row}
	<table>

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

	</table>
{/foreach}

Vedere anche i filtri batch e di gruppo.

{for}

Scriviamo il ciclo esattamente come in PHP:

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

Il tag può anche essere scritto come n:attribute:

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

Una variante con una condizione nel tag finale corrisponde al ciclo do-while di PHP:

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

{continueIf} {skipIf} {breakIf}

Esistono tag speciali che possono essere utilizzati per controllare qualsiasi ciclo: {continueIf ?} e {breakIf ?}, che saltano rispettivamente all'iterazione successiva e terminano il ciclo, se le condizioni sono soddisfatte:

{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. Quindi non ci sono buchi nella numerazione quando si stampa $iterator->counter e si saltano alcuni elementi. Anche la clausola {else} sarà resa quando si saltano tutti gli elementi.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>Sorry, no adult users in this list</em></li>
	{/foreach}
</ul>

{exitIf}

Termina il rendering di un modello o di un blocco quando viene soddisfatta una condizione (cioè “uscita anticipata”).

{exitIf !$messages}

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

Inclusione di modelli

{include 'file.latte'}

Vedi anche {include block}

Il tag {include} carica e rende il modello specificato. Nel nostro linguaggio PHP preferito è come:

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

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

È possibile passare variabili al modello inserito nel modo seguente:

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

Il nome del modello può essere una qualsiasi espressione PHP:

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

Il contenuto inserito può essere modificato utilizzando dei filtri. L'esempio seguente rimuove tutto il materiale HTML e regola il caso:

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

L'ereditarietà del template non è coinvolta in questo per impostazione predefinita. Sebbene sia possibile aggiungere tag di blocco ai template che sono inclusi, essi non sostituiranno i blocchi corrispondenti nel template in cui sono inclusi. Si pensi agli include come a parti indipendenti e protette di pagine o moduli. Questo comportamento può essere cambiato 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 è una questione di caricatore.

{sandbox}

Quando si include un modello creato da un utente finale, si dovrebbe considerare la possibilità di metterlo in sandbox (maggiori informazioni nella documentazione di sandbox):

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

{block}

Vedi anche {block name}

I blocchi senza nome servono per applicare filtri a una parte del modello. Ad esempio, è possibile applicare un filtro striscia per rimuovere gli spazi non necessari:

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

Gestione delle eccezioni

{try}

Questo tag rende estremamente facile la costruzione di modelli robusti.

Se si verifica un'eccezione durante la resa del blocco {try}, l'intero blocco viene gettato via e la resa continuerà dopo di esso:

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

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

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Sorry, the tweets could not be loaded.</p>
{/try}

Il tag può anche essere scritto come n:attribute:

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

È anche possibile definire un proprio gestore di eccezioni per esempio per la registrazione:

{rollback}

Il blocco {try} può anche essere fermato e saltato manualmente usando {rollback}. In questo modo non è necessario controllare in anticipo tutti i dati di input e solo durante il rendering si può decidere se ha senso eseguire il rendering dell'oggetto.

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

Variabili

{var} {default}

Creeremo 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 le variabili solo se non esistono:

{default $lang = 'cs'}

È anche possibile specificare i tipi di variabili. Per ora sono informative e Latte non le controlla.

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

{parameters}

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

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

Le variabili $a e $b senza un valore predefinito hanno automaticamente un valore predefinito di null. I tipi dichiarati sono ancora informativi e Latte non li controlla.

Oltre alle variabili dichiarate, non vengono passate nel template. Questa è una differenza rispetto al tag {default}.

{capture}

Utilizzando il tag {capture} è possibile catturare l'output in una variabile:

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

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

Il tag può anche essere scritto come n:attribute, come qualsiasi tag a coppie:

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

L'output HTML viene memorizzato nella variabile $var come oggetto Latte\Runtime\Html per evitare escape indesiderati durante la stampa.

Altri

{contentType}

Usare il tag per specificare il tipo di contenuto che il modello rappresenta. Le opzioni sono:

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

Il suo uso è importante perché imposta l'escape sensibile al contesto e solo allora Latte può eseguire l'escape correttamente. Ad esempio, {contentType xml} passa alla modalità XML, {contentType text} disattiva completamente l'escape.

Se il parametro è un tipo MIME completo, come application/xml, invia anche un'intestazione HTTP Content-Type al browser:

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

{debugbreak}

Specifica il punto in cui l'esecuzione del codice si interrompe. Viene utilizzato a scopo di debug per consentire al programmatore di ispezionare l'ambiente di runtime e di assicurarsi che il codice venga eseguito come previsto. Supporta Xdebug. Inoltre, è possibile specificare una condizione in cui il codice deve interrompersi.

{debugbreak}                {* interrompe il programma *}

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

{do}

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

{do $num++}

{dump}

Esegue il dump di una variabile o del contesto corrente.

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

{dump}       {* cancella tutte le variabili definite *}

Richiede il pacchetto Tracy.

{php}

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

{spaceless}

Rimuove gli spazi bianchi non necessari. È simile al filtro senza spazi.

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

Uscite:

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

Il tag può essere scritto anche come n:attribute:

{syntax}

I tag Latte non devono essere racchiusi solo tra parentesi graffe singole. È possibile scegliere un altro separatore, anche in fase di esecuzione. Questo viene fatto da {syntax…}, dove il parametro può essere:

• double: {{...}}
• off: disabilita completamente i tag Latte

Usando la notazione n:attribute si può disabilitare Latte solo per un blocco JavaScript:

<script n:syntax="off">
	var obj = {var: 123}; // this isn't a tag any more
</script>

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

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

{trace}

Lancia un'eccezione Latte\RuntimeException, la cui traccia di stack è nello spirito dei template. Quindi, invece di chiamare funzioni e metodi, comporta la chiamata di blocchi e l'inserimento di modelli. Se si utilizza uno strumento per visualizzare chiaramente le eccezioni lanciate, come Tracy, si vedrà chiaramente lo stack delle chiamate, compresi tutti gli argomenti passati.

Aiutanti dei tag HTML

n:classe

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

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

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

Inoltre, ho bisogno 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 può generare attributi HTML arbitrari 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, visualizza ad es:

<input type="checkbox">

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

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

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 con il valore della variabile, quindi per $heading === 'h3' si scrive:

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

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

n:ifcontent

Impedisce che venga stampato un elemento HTML vuoto, cioè un elemento contenente solo spazi bianchi.

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

A seconda dei valori della variabile $error questo verrà stampato:

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

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

Traduzione

Per far funzionare i tag di traduzione, è necessario impostare translator. Si può anche usare il filtro translate per la traduzione.

{_...}

Traduce i valori in altre lingue.

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

Al traduttore possono essere passati anche altri parametri:

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

{translate}

Překládá části šablony:

<h1>{translate}Order{/translate}</h1>

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

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

<h1 n:translate>Order</h1>