Passare variabili tra i template

Questa guida spiega come vengono passate le variabili tra i template in Latte usando i vari tag, come {include}, {import}, {embed}, {layout}, {sandbox} e altri. Imparerete inoltre come lavorare con le variabili all'interno dei tag {block} e {define} e a cosa serve il tag {parameters}.

Tipi di variabili

Le variabili in Latte si possono dividere in tre categorie, a seconda di come e dove vengono definite:

Le variabili di ingresso sono quelle passate al template dall'esterno, per esempio da uno script PHP o con un tag come {include}.

$latte->render('template.latte', ['userName' => 'Jan', 'userAge' => 30]);

Le variabili circostanti sono le variabili esistenti nel punto in cui si trova un determinato tag. Comprendono tutte le variabili di ingresso e le altre variabili create con tag come {var}, {default} o all'interno di un ciclo {foreach}.

{foreach $users as $user}
	{include 'userBox.latte', user: $user}
{/foreach}

Le variabili esplicite sono quelle indicate direttamente in un tag e inviate al template di destinazione.

{include 'userBox.latte', name: $user->name, age: $user->age}

{block}

Il tag {block} serve a definire blocchi di codice riutilizzabili, che possono essere personalizzati o estesi nei template che ereditano. Le variabili circostanti definite prima del blocco sono disponibili al suo interno, ma le eventuali modifiche alle variabili si riflettono solo dentro quel blocco.

{var $foo = 'original'}
{block example}
	{var $foo = 'modified'}
{/block}

{$foo}    // stampa: original

{define}

Il tag {define} serve a creare blocchi che vengono renderizzati solo quando li si richiama con {include}. Le variabili disponibili in questi blocchi dipendono dal fatto che nella definizione siano dichiarati dei parametri. Un blocco con parametri dichiarati ha accesso sia a quei parametri sia a tutte le variabili di ingresso del template in cui è definito. Un blocco senza parametri ha accesso a quelle stesse variabili di ingresso. In nessuno dei due casi sono disponibili le variabili circostanti.

{define hello}
	{* ha accesso a tutte le variabili di ingresso del template *}
{/define}

{define hello $name}
	{* ha accesso al parametro $name e alle variabili di ingresso *}
{/define}

{parameters}

Il tag {parameters} serve a dichiarare esplicitamente, all'inizio del template, le variabili di ingresso attese. In questo modo potete documentare facilmente le variabili attese e i loro tipi di dato. È anche possibile definire dei valori predefiniti.

{parameters int $age, string $name = 'unknown'}
<p>Età: {$age}, Nome: {$name}</p>

{include file}

Il tag {include file} serve a inserire un intero template. A questo template vengono passate sia le variabili di ingresso del template in cui il tag è usato, sia le variabili definite esplicitamente. Il template di destinazione può però limitarne l'ambito con {parameters}.

{include 'profile.latte', userId: $user->id}

{include block}

Quando si inserisce un blocco definito nello stesso template, gli vengono passate tutte le variabili circostanti e quelle definite esplicitamente:

{define blockName}
	<p>Nome: {$name}, Età: {$age}</p>
{/define}

{var $name = 'Jan', $age = 30}
{include blockName}

In questo esempio le variabili $name e $age vengono passate al blocco blockName. Lo stesso comportamento vale per {include parent}.

Quando si inserisce un blocco da un altro template, vengono passate solo le variabili di ingresso e quelle definite esplicitamente. Le variabili circostanti non sono automaticamente disponibili.

{include blockInOtherTemplate, name: $name, age: $age}

{layout} oppure {extends}

Questi tag definiscono un layout al quale vengono passate le variabili di ingresso del template figlio e le variabili create nel codice prima dei blocchi:

{layout 'layout.latte'}
{var $seo = 'index, follow'}

Template layout.latte:

<head>
	<meta name="robots" content="{$seo}">
</head>

{embed}

Il tag {embed} è simile al tag {include}, ma permette di incorporare blocchi nel template. A differenza di {include}, vengono passate solo le variabili dichiarate esplicitamente:

{embed 'menu.latte', items: $menuItems}
{/embed}

In questo esempio il template menu.latte ha accesso solo alla variabile $items.

Al contrario, i blocchi dentro {embed} hanno accesso a tutte le variabili circostanti:

{var $name = 'Jan'}
{embed 'menu.latte', items: $menuItems}
	{block foo}
		{$name}
	{/block}
{/embed}

{import}

Il tag {import} serve a caricare blocchi da altri template. Ai blocchi importati vengono passate sia le variabili di ingresso sia quelle dichiarate esplicitamente.

{import 'buttons.latte'}

{sandbox}

Il tag {sandbox} isola il template per un'elaborazione sicura. Le variabili vengono passate esclusivamente in modo esplicito.

{sandbox 'secure.latte', data: $secureData}
versione: 3.x