Passage de variables entre templates

Ce guide vous explique comment les variables sont passées entre les templates dans Latte en utilisant différentes balises comme {include}, {import}, {embed}, {layout}, {sandbox}, et d'autres. Vous apprendrez également comment travailler avec les variables dans les balises {block} et {define}, et à quoi sert la balise {parameters}.

Types de variables

Les variables dans Latte peuvent être divisées en trois catégories selon comment et où elles sont définies :

Variables d'entrée sont celles qui sont passées au template depuis l'extérieur, par exemple depuis un script PHP ou en utilisant une balise comme {include}.

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

Variables environnantes sont les variables existant à l'endroit d'une certaine balise. Elles incluent toutes les variables d'entrée et d'autres variables créées à l'aide de balises comme {var}, {default} ou dans le cadre d'une boucle {foreach}.

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

Variables explicites sont celles qui sont directement spécifiées à l'intérieur de la balise et sont envoyées au template cible.

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

{block}

La balise {block} est utilisée pour définir des blocs de code réutilisables qui peuvent être personnalisés ou étendus dans les templates hérités. Les variables environnantes définies avant le bloc sont disponibles à l'intérieur du bloc, mais toute modification des variables n'est effective qu'à l'intérieur de ce bloc.

{var $foo = 'original'}
{block example}
	{var $foo = 'modifié'}
{/block}

{$foo}    // affiche : original

{define}

La balise {define} sert à créer des blocs qui ne sont rendus qu'après leur appel via {include}. Les variables disponibles à l'intérieur de ces blocs dépendent de si des paramètres sont spécifiés dans la définition. Si oui, elles n'ont accès qu'à ces paramètres. Sinon, elles ont accès à toutes les variables d'entrée du template dans lequel les blocs sont définis.

{define hello}
	{* a accès à toutes les variables d'entrée du template *}
{/define}

{define hello $name}
	{* a accès uniquement au paramètre $name *}
{/define}

{parameters}

La balise {parameters} sert à déclarer explicitement les variables d'entrée attendues au début du template. De cette manière, il est facile de documenter les variables attendues et leurs types de données. Il est également possible de définir des valeurs par défaut.

{parameters int $age, string $name = 'inconnu'}
<p>Âge : {$age}, Nom : {$name}</p>

{include file}

La balise {include file} sert à inclure un template entier. Les variables d'entrée du template dans lequel la balise est utilisée, ainsi que les variables explicitement définies, sont passées à ce template. Cependant, le template cible peut limiter la portée à l'aide de {parameters}.

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

{include block}

Lorsque vous incluez un bloc défini dans le même template, toutes les variables environnantes et explicitement définies lui sont passées :

{define blockName}
	<p>Nom : {$name}, Âge : {$age}</p>
{/define}

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

Dans cet exemple, les variables $name et $age sont passées au bloc blockName. {include parent} se comporte de la même manière.

Lors de l'inclusion d'un bloc d'un autre template, seules les variables d'entrée et celles explicitement définies sont passées. Les variables environnantes ne sont pas automatiquement disponibles.

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

{layout} ou {extends}

Ces balises définissent le layout auquel sont passées les variables d'entrée du template enfant ainsi que les variables créées dans le code avant les blocs :

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

Template layout.latte :

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

{embed}

La balise {embed} est similaire à la balise {include}, mais permet d'intégrer des blocs dans le template. Contrairement à {include}, seules les variables explicitement déclarées sont passées :

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

Dans cet exemple, le template menu.latte n'a accès qu'à la variable $items.

Inversement, dans les blocs à l'intérieur de {embed}, toutes les variables environnantes sont accessibles :

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

{import}

La balise {import} est utilisée pour charger des blocs depuis d'autres templates. Les variables d'entrée ainsi que les variables explicitement déclarées sont transmises aux blocs importés.

{import 'buttons.latte'}

{sandbox}

La balise {sandbox} isole le template pour un traitement sécurisé. Les variables sont passées exclusivement de manière explicite.

{sandbox 'secure.latte', data: $secureData}
version: 3.0