Balises Latte

Aperçu et description de toutes les balises du système de templates Latte qui sont disponibles par défaut.

Affichage

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

En Latte, la balise {=...} est utilisée pour afficher n'importe quelle expression en sortie. Latte se soucie de votre confort, donc si l'expression commence par une variable ou un appel de fonction, il n'est pas nécessaire d'écrire le signe égal. Ce qui signifie en pratique qu'il n'est presque jamais nécessaire de l'écrire :

Nom : {$name} {$surname}<br>
Âge : {date('Y') - $birth}<br>

Comme expression, vous pouvez écrire tout ce que vous connaissez de PHP. Vous n'avez tout simplement pas besoin d'apprendre un nouveau langage. Par exemple :

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

S'il vous plaît, ne cherchez aucun sens dans l'exemple précédent, mais si vous en trouvez un, écrivez-nous :-)

Échappement de la sortie

Quelle est la tâche la plus importante d'un système de templates ? Empêcher les failles de sécurité. Et c'est exactement ce que fait Latte chaque fois que vous affichez quelque chose. Il l'échappe automatiquement :

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

Pour être précis, Latte utilise l'échappement contextuel, ce qui est une chose si importante et unique que nous lui avons consacré un chapitre séparé.

Et si vous affichez du contenu encodé en HTML provenant d'une source fiable ? Alors, vous pouvez facilement désactiver l'échappement :

{$trustedHtmlString|noescape}

Une mauvaise utilisation du filtre noescape peut entraîner une vulnérabilité XSS ! Ne l'utilisez jamais si vous n'êtes pas absolument sûr de ce que vous faites et que la chaîne affichée provient d'une source fiable.

Affichage en JavaScript

Grâce à l'échappement contextuel, il est merveilleusement facile d'afficher des variables à l'intérieur de JavaScript et Latte s'occupe de l'échappement correct.

La variable ne doit pas nécessairement être une chaîne, n'importe quel type de données est pris en charge, qui sera ensuite encodé en JSON :

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

Génère :

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

C'est aussi la raison pour laquelle on n'écrit pas de guillemets autour de la variable : Latte les ajoute lui-même pour les chaînes. Et si vous vouliez insérer une variable de chaîne dans une autre chaîne, concaténez-les simplement :

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

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

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

Filtres

L'expression affichée peut être modifiée par un filtre. Ainsi, par exemple, nous convertissons une chaîne en majuscules et la raccourcissons à un maximum de 30 caractères :

{$string|upper|truncate:30}

Vous pouvez également appliquer des filtres à des parties partielles de l'expression de cette manière :

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

Conditions

{if} {elseif} {else}

Les conditions se comportent de la même manière que leurs homologues en PHP. Vous pouvez y utiliser les mêmes expressions que vous connaissez de PHP, vous n'avez pas besoin d'apprendre un nouveau langage.

{if $product->inStock > Stock::Minimum}
	En stock
{elseif $product->isOnWay()}
	En route
{else}
	Non disponible
{/if}

Comme toute balise paire, la paire {if} ... {/if} peut également être écrite sous forme de n:attribut, par exemple :

<p n:if="$count > 0">{$count} pièces en stock</p>

Savez-vous que vous pouvez ajouter le préfixe tag- aux n:attributs ? Alors la condition ne s'appliquera qu'à l'affichage des balises HTML et le contenu entre elles sera toujours affiché :

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

{* affiche 'Hello' si $clickable est faux *}
{* affiche '<a href="...">Hello</a>' si $clickable est vrai *}

Génial.

n:else

Si vous écrivez la condition {if} ... {/if} sous forme de n:attribut, vous avez la possibilité d'indiquer également une branche alternative à l'aide de n:else:

<strong n:if="$count > 0">{$count} pièces en stock</strong>

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

L'attribut n:else peut également être utilisé en paire avec n:ifset, n:foreach, n:try, n:ifcontent et n:ifchanged.

{/if $cond}

Vous serez peut-être surpris que l'expression dans la condition {if} puisse également être indiquée dans la balise de fin. C'est utile dans les situations où, lors de l'ouverture de la condition, nous ne connaissons pas encore sa valeur. Appelons cela une décision différée.

Par exemple, nous commençons à afficher un tableau avec des enregistrements de la base de données et ce n'est qu'après avoir terminé l'affichage que nous réalisons qu'il n'y avait aucun enregistrement dans la base de données. Nous mettons donc une condition pour cela dans la balise de fin {/if} et s'il n'y a aucun enregistrement, rien de tout cela ne sera affiché :

{if}
	<h1>Liste des lignes de la base de données</h1>

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

Pratique, n'est-ce pas ?

Dans la condition différée, on peut aussi utiliser {else}, mais pas {elseif}.

{ifset} {elseifset}

Voir aussi {ifset block}

À l'aide de la condition {ifset $var}, nous vérifions si la variable (ou plusieurs variables) existe et a une valeur non-null. En fait, c'est la même chose que if (isset($var)) en PHP. Comme toute balise paire, elle peut également être écrite sous forme de n:attribut, montrons-le comme exemple :

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

{ifchanged}

{ifchanged} vérifie si la valeur de la variable a changé depuis la dernière itération dans la boucle (foreach, for ou while).

Si nous indiquons une ou plusieurs variables dans la balise, elle vérifiera si l'une d'elles a changé et affichera le contenu en conséquence. Par exemple, l'exemple suivant affiche la première lettre du nom comme titre chaque fois qu'elle change lors de l'affichage des noms :

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

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

Cependant, si nous n'indiquons aucun argument, le contenu rendu sera comparé à son état précédent. Cela signifie que dans l'exemple précédent, nous pouvons tout à fait omettre l'argument dans la balise. Et bien sûr, nous pouvons aussi utiliser un n:attribut:

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

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

À l'intérieur de {ifchanged}, on peut aussi indiquer une clause {else}.

{switch} {case} {default}

Compare la valeur avec plusieurs options. C'est un équivalent de l'instruction conditionnelle switch que vous connaissez de PHP. Cependant, Latte l'améliore :

• utilise une comparaison stricte (===)
• n'a pas besoin de break

C'est donc l'équivalent exact de la structure match introduite avec PHP 8.0.

{switch $transport}
	{case train}
		En train
	{case plane}
		En avion
	{default}
		Autrement
{/switch}

La clause {case} peut contenir plusieurs valeurs séparées par des virgules :

{switch $status}
{case $status::New}<b>nouvel élément</b>
{case $status::Sold, $status::Unknown}<i>non disponible</i>
{/switch}

Boucles

En Latte, vous trouverez toutes les boucles que vous connaissez de PHP : foreach, for et while.

{foreach}

Nous écrivons la boucle exactement comme en PHP :

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

De plus, elle a quelques astuces pratiques dont nous allons parler maintenant.

Latte vérifie par exemple si les variables créées n'écrasent pas accidentellement des variables globales du même nom. Cela sauve des situations où vous comptez sur le fait que $lang contient la langue actuelle de la page, et ne réalisez pas que foreach $langs as $lang vous a écrasé cette variable.

La boucle foreach peut également être écrite de manière très élégante et concise à l'aide d'un n:attribut:

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

Savez-vous que vous pouvez ajouter le préfixe inner- aux n:attributs ? Alors seul l'intérieur de l'élément sera répété dans la boucle :

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

Donc, quelque chose comme ceci sera affiché :

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

{else}

À l'intérieur de la boucle foreach, on peut indiquer une clause {else}, dont le contenu s'affichera si la boucle est vide :

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Désolé, il n'y a aucun utilisateur dans cette liste</em></li>
	{/foreach}
</ul>

$iterator

À l'intérieur de la boucle foreach, Latte crée la variable $iterator, à l'aide de laquelle nous pouvons obtenir des informations utiles sur la boucle en cours :

• $iterator->first – est-ce la première itération de la boucle ?
• $iterator->last – est-ce la dernière itération ?
• $iterator->counter – quelle est l'itération en cours, comptée à partir de un ?
• $iterator->counter0 – quelle est l'itération en cours, comptée à partir de zéro ?
• $iterator->odd – est-ce une itération impaire ?
• $iterator->even – est-ce une itération paire ?
• $iterator->parent – l'itérateur entourant celui actuel
• $iterator->nextValue – l'élément suivant dans la boucle
• $iterator->nextKey – la clé de l'élément suivant dans la boucle

{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 est malin et $iterator->last fonctionne non seulement pour les tableaux, mais aussi lorsque la boucle s'exécute sur un itérateur général, où le nombre d'éléments n'est pas connu à l'avance.

{first} {last} {sep}

Ces balises peuvent être utilisées à l'intérieur de la boucle {foreach}. Le contenu de {first} est rendu s'il s'agit de la première itération. Le contenu de {last} est rendu… devinerez-vous ? Oui, s'il s'agit de la dernière itération. Ce sont en fait des raccourcis pour {if $iterator->first} et {if $iterator->last}.

Les balises peuvent également être utilisées élégamment comme n:attribut:

{foreach $rows as $row}
	{first}<h1>Liste des noms</h1>{/first}

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

	<hr n:last>
{/foreach}

Le contenu de la balise {sep} est rendu si l'itération n'est pas la dernière, il est donc utile pour afficher des séparateurs, par exemple des virgules entre les éléments affichés :

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

C'est assez pratique, n'est-ce pas ?

{iterateWhile}

Simplifie le regroupement de données linéaires lors de l'itération dans une boucle foreach en effectuant l'itération dans une boucle imbriquée tant que la condition est remplie. Lisez le tutoriel détaillé.

Peut aussi remplacer élégamment {first} et {last} dans l'exemple ci-dessus :

{foreach $rows as $row}
	<table>

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

	</table>
{/foreach}

Voir aussi les filtres batch et group.

{for}

Nous écrivons la boucle exactement comme en PHP :

{for $i = 0; $i < 10; $i++}
	<span>Élément {$i}</span>
{/for}

La balise peut également être utilisée comme n:attribut:

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

{while}

Nous écrivons à nouveau la boucle exactement comme en PHP :

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

Ou comme n:attribut:

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

Une variante avec la condition dans la balise de fin est également possible, ce qui correspond en PHP à la boucle do-while :

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

{continueIf} {skipIf} {breakIf}

Pour contrôler n'importe quelle boucle, on peut utiliser les balises {continueIf ?} et {breakIf ?}, qui passent à l'élément suivant resp. terminent la boucle si la condition est remplie :

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

La balise {skipIf} est très similaire à {continueIf}, mais n'incrémente pas le compteur $iterator->counter, donc si nous l'affichons et sautons en même temps certains éléments, il n'y aura pas de trous dans la numérotation. Et aussi la clause {else} sera rendue si nous sautons tous les éléments.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>Désolé, il n'y a aucun adulte dans cette liste</em></li>
	{/foreach}
</ul>

{exitIf}

Termine le rendu du template ou du bloc si la condition est remplie (appelé “early exit”).

{exitIf !$messages}

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

Inclusion de template

{include 'file.latte'}

Voir aussi {include block}

La balise {include} charge et rend le template spécifié. Si nous parlions dans le langage de notre langage PHP préféré, ce serait quelque chose comme :

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

Les templates inclus n'ont pas accès aux variables du contexte actif, ils n'ont accès qu'aux variables globales.

Vous pouvez passer des variables au template inclus de cette manière :

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

Le nom du template peut être n'importe quelle expression PHP :

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

Le contenu inclus peut être modifié à l'aide de filtres. L'exemple suivant supprime tout le HTML et modifie la casse des lettres :

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

Par défaut, l'héritage de templates ne joue aucun rôle dans ce cas. Même si nous pouvons utiliser des blocs dans le template inclus, les blocs correspondants dans le template dans lequel il est inclus ne seront pas remplacés. Pensez aux templates inclus comme des parties de pages ou de modules distinctes et isolées. Ce comportement peut être modifié à l'aide du modificateur with blocks:

{include 'template.latte' with blocks}

La relation entre le nom de fichier spécifié dans la balise et le fichier sur le disque dépend du chargeur.

{sandbox}

Lors de l'inclusion d'un template créé par l'utilisateur final, vous devriez envisager le mode sandbox (plus d'informations dans la documentation du sandbox):

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

{block}

Voir aussi {block name}

Les blocs sans nom servent de moyen pour appliquer des filtres à une partie du template. Par exemple, on peut ainsi appliquer le filtre strip, qui supprime les espaces inutiles :

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

Gestion des exceptions

{try}

Grâce à cette balise, il est extrêmement facile de créer des templates robustes.

Si une exception se produit lors du rendu du bloc {try}, tout le bloc est abandonné et le rendu continue après lui :

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

Le contenu de la clause facultative {else} n'est rendu que lorsqu'une exception se produit :

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Désolé, impossible de charger les tweets.</p>
{/try}

La balise peut également être utilisée comme n:attribut:

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

Il est également possible de définir un gestionnaire d'exceptions personnalisé, par exemple pour la journalisation.

{rollback}

Le bloc {try} peut également être arrêté et sauté manuellement à l'aide de {rollback}. Grâce à cela, vous n'avez pas besoin de vérifier toutes les données d'entrée à l'avance et vous pouvez décider pendant le rendu que vous ne voulez pas du tout rendre l'objet :

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

Variables

{var} {default}

Nous créons de nouvelles variables dans le template avec la balise {var}:

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

{* Déclaration multiple *}
{var $name = 'John Smith', $age = 27}

La balise {default} fonctionne de manière similaire, mais ne crée des variables que si elles n'existent pas. Si la variable existe déjà et contient la valeur null, elle ne sera pas écrasée :

{default $lang = 'fr'}

Vous pouvez également indiquer les types de variables. Pour l'instant, ils sont informatifs et Latte ne les vérifie pas.

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

{parameters}

Tout comme une fonction déclare ses paramètres, un template peut également déclarer ses variables au début :

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

Les variables $a et $b sans valeur par défaut spécifiée ont automatiquement la valeur par défaut null. Les types déclarés sont pour l'instant informatifs et Latte ne les vérifie pas.

D'autres variables que celles déclarées ne sont pas transmises au template. C'est ce qui la différencie de la balise {default}.

{capture}

Capture la sortie dans une variable :

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

<p>Capturé : {$var}</p>

La balise peut, comme toute balise paire, être également écrite comme un n:attribut:

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

La sortie HTML est enregistrée dans la variable $var sous forme d'objet Latte\Runtime\Html, pour éviter un échappement indésirable lors de l'affichage.

Autres

{contentType}

Avec cette balise, vous spécifiez le type de contenu que représente le template. Les options sont :

• html (type par défaut)
• xml
• javascript
• css
• calendar (iCal)
• text

Son utilisation est importante car elle définit l'échappement contextuel et ce n'est qu'ainsi qu'elle peut échapper correctement. Par exemple, {contentType xml} passe en mode XML, {contentType text} désactive complètement l'échappement.

Si le paramètre est un type MIME complet, comme par exemple application/xml, alors il envoie également l'en-tête HTTP Content-Type au navigateur :

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

{debugbreak}

Indique l'endroit où l'exécution du programme sera suspendue et le débogueur démarré, afin que le programmeur puisse inspecter l'environnement d'exécution et vérifier si le programme fonctionne comme prévu. Prend en charge Xdebug. On peut ajouter une condition qui détermine quand le programme doit être suspendu.

{debugbreak}                {* suspend le programme *}

{debugbreak $counter == 1}  {* suspend le programme si la condition est remplie *}

{do}

Exécute du code PHP et n'affiche rien. Comme pour toutes les autres balises, le code PHP s'entend comme une seule expression, voir limitations de PHP.

{do $num++}

{dump}

Affiche une variable ou le contexte actuel.

{dump $name} {* Affiche la variable $name *}

{dump}       {* Affiche toutes les variables actuellement définies *}

Nécessite la bibliothèque Tracy.

{php}

Permet d'exécuter n'importe quel code PHP. La balise doit être activée à l'aide de l'extension RawPhpExtension.

{spaceless}

Supprime les espaces blancs inutiles de la sortie. Fonctionne de manière similaire au filtre spaceless.

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

Génère

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

La balise peut également être écrite comme un n:attribut.

{syntax}

Les balises Latte ne doivent pas nécessairement être délimitées uniquement par des accolades simples. Nous pouvons choisir un autre délimiteur, et ce même à l'exécution. La balise {syntax …} sert à cela, où l'on peut indiquer comme paramètre :

• double: {{...}}
• off: désactive complètement le traitement des balises Latte

En utilisant les n:attributs, on peut désactiver Latte par exemple pour un seul bloc JavaScript :

<script n:syntax="off">
	var obj = {var: 123}; // ceci n'est plus une balise
</script>

Latte peut être utilisé très confortablement à l'intérieur de JavaScript, il suffit d'éviter les constructions comme dans cet exemple, où une lettre suit immédiatement {, voir Latte à l'intérieur de JavaScript ou CSS.

Si vous désactivez Latte à l'aide de {syntax off} (c'est-à-dire avec la balise, pas le n:attribut), il ignorera strictement toutes les balises jusqu'à {/syntax}

{trace}

Déclenche une exception Latte\RuntimeException, dont la trace de la pile (stack trace) est dans l'esprit des templates. C'est-à-dire qu'au lieu des appels de fonctions et de méthodes, elle contient des appels de blocs et des inclusions de templates. Si vous utilisez un outil pour afficher clairement les exceptions levées, comme par exemple Tracy, la pile d'appels s'affichera clairement, y compris tous les arguments passés.

Aides pour le codeur HTML

n:class

Grâce à n:class, vous pouvez très facilement générer l'attribut HTML class exactement selon vos souhaits.

Exemple : j'ai besoin que l'élément actif ait la classe active:

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

Et de plus, que le premier élément ait les classes first et main:

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

Et que tous les éléments aient la classe list-item:

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

Incroyablement simple, n'est-ce pas ?

n:attr

L'attribut n:attr peut générer n'importe quels attributs HTML avec la même élégance que n:class.

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

En fonction des valeurs retournées, affiche par ex. :

<input type="checkbox">

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

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

n:tag

L'attribut n:tag peut changer dynamiquement le nom de l'élément HTML.

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

Si $heading === null, la balise <h1> sera affichée sans changement. Sinon, le nom de l'élément sera changé en la valeur de la variable, donc pour $heading === 'h3', s'affichera :

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

Comme Latte est un système de templates sécurisé, il vérifie si le nouveau nom de balise est valide et ne contient aucune valeur indésirable ou nuisible.

n:ifcontent

Empêche l'affichage d'un élément HTML vide, c'est-à-dire un élément ne contenant rien d'autre que des espaces.

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

Affiche en fonction de la valeur de la variable $error:

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

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

Traductions

Pour que les balises de traduction fonctionnent, il faut activer le traducteur. Pour la traduction, vous pouvez également utiliser le filtre translate.

{_...}

Traduit les valeurs dans d'autres langues.

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

On peut également passer d'autres paramètres au traducteur :

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

{translate}

Traduit des parties du template :

<h1>{translate}Commande{/translate}</h1>

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

La balise peut également être écrite comme un n:attribut, pour traduire l'intérieur de l'élément :

<h1 n:translate>Commande</h1>