Balises Latte

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

Affichage

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

Dans Latte, la balise {=...} sert à afficher n'importe quelle expression. Latte se soucie de votre confort : si l'expression commence par une variable ou un appel de fonction, il n'y a pas besoin d'écrire le signe égal. En pratique, cela signifie qu'il n'est presque jamais nécessaire de l'écrire :

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

Vous pouvez écrire comme expression tout ce que vous connaissez de PHP. Vous n'avez tout simplement pas de nouveau langage à apprendre. Par exemple :

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

Ne cherchez surtout pas de sens à l'exemple précédent, mais si vous en trouvez un, faites-le-nous savoir :-)

É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 pratique l'échappement sensible au contexte, une fonctionnalité si importante et si unique que nous lui avons consacré un chapitre entier.

Et si vous affichez du contenu HTML provenant d'une source de confiance ? Vous pouvez alors désactiver l'échappement sans difficulté :

{$trustedHtmlString|noescape}

Un mauvais usage du filtre noescape peut ouvrir une vulnérabilité XSS ! Ne l'utilisez jamais sans être absolument certain de ce que vous faites et que la chaîne affichée provient d'une source de confiance.

Affichage en JavaScript

Grâce à l'échappement sensible au contexte, il est merveilleusement simple d'afficher des variables à l'intérieur de JavaScript : Latte se charge de l'échappement correct.

La variable n'a pas à être une chaîne ; tous les types de données sont pris en charge et encodés en JSON :

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

Génère :

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

C'est aussi pourquoi vous ne devez pas mettre de guillemets autour de la variable : Latte les ajoute automatiquement pour les chaînes. Et si vous voulez insérer une variable de type chaîne dans une autre chaîne, concaténez-les simplement :

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

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

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

Filtres

L'expression affichée peut être modifiée par des filtres. Celui-ci, par exemple, met la chaîne en majuscules et la raccourcit à 30 caractères au maximum :

{$string|upper|truncate:30}

Vous pouvez aussi appliquer des filtres à une partie d'une expression, comme ceci :

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

Conditions

{if} {elseif} {else}

Les conditions se comportent exactement comme leurs équivalents PHP. Vous pouvez utiliser les mêmes expressions qu'en PHP ; vous n'avez pas de nouveau langage à apprendre.

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

Comme toute balise paire, la paire {if} ... {/if} peut aussi s'écrire avec un n:attribut, par exemple :

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

Saviez-vous que vous pouvez ajouter le préfixe tag- aux n:attributs ? La condition ne portera alors que sur l'affichage des balises HTML, le contenu situé entre elles étant toujours affiché :

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

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

Épatant.

n:else n:elseif

Si vous écrivez la condition {if} ... {/if} sous la forme d'un n:attribut, vous pouvez indiquer des branches alternatives avec n:else (depuis 3.0.12) et n:elseif (depuis 3.1) :

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

<em n:elseif="$count < 0">Nombre invalide</em>

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

L'attribut n:else peut aussi s'utiliser avec n:ifset, n:foreach, n:try, n:ifcontent et n:ifchanged.

{/if $cond}

Vous serez peut-être surpris d'apprendre que l'expression de la condition {if} peut aussi être indiquée dans la balise fermante. C'est utile quand nous ne connaissons pas encore sa valeur à l'ouverture de la condition. 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'une fois la sortie terminée que nous constatons qu'il n'y avait aucun enregistrement. Nous plaçons donc la condition dans la balise fermante {/if} et, s'il n'y a aucun enregistrement, rien de tout cela ne sera affiché :

{if}
	<h1>List of rows from the database</h1>

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

Pratique, non ?

Vous pouvez aussi utiliser {else} dans une condition différée, mais pas {elseif}.

{ifset} {elseifset}

Voyez aussi {ifset block}

Utilisez la condition {ifset $var} pour déterminer si une variable (ou plusieurs variables) existe et a une valeur non nulle. C'est en fait la même chose que if (isset($var)) en PHP. Comme toute balise paire, elle peut aussi s'écrire avec un n:attribut ; voici donc un exemple :

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

{ifchanged}

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

Si nous indiquons une ou plusieurs variables dans la balise, il vérifie si l'une d'elles a changé et affiche le contenu en conséquence. L'exemple suivant affiche ainsi la première lettre d'un nom comme titre chaque fois qu'elle change au fil de l'énumération des noms :

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

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

Si aucun argument n'est donné, c'est en revanche le contenu rendu lui-même qui sera comparé à son état précédent. Dans l'exemple précédent, nous pouvons donc omettre l'argument sans risque. Et nous pouvons bien sûr utiliser un n:attribut :

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

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

Une clause {else} peut aussi s'utiliser à l'intérieur de {ifchanged}.

{switch} {case} {default}

Compare une valeur à plusieurs possibilités. C'est semblable à l'instruction switch connue de PHP. Latte l'améliore toutefois :

• il utilise la comparaison stricte (===)
• il ne demande pas de break

Il se rapproche donc beaucoup de la structure match introduite par 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 article</b>
{case $status::Sold, $status::Unknown}<i>non disponible</i>
{/switch}

Boucles

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

{foreach}

Vous écrivez la boucle exactement comme en PHP :

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

Elle a en outre quelques fonctionnalités pratiques dont nous allons parler.

Latte vérifie par exemple que les variables créées n'écrasent pas par inadvertance des variables globales du même nom. Cela vous évite les situations où vous attendez que $lang contienne la langue courante de la page sans vous rendre compte que foreach $langs as $lang a écrasé cette variable.

La boucle foreach peut aussi s'écrire de façon très élégante et économe avec un n:attribut :

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

Saviez-vous que vous pouvez ajouter le préfixe inner- aux n:attributs ? Seule la partie intérieure de l'élément sera alors répétée dans la boucle :

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

Cela affiche donc quelque chose comme :

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

{else}

À l'intérieur de la boucle foreach, vous pouvez indiquer une clause {else} dont le contenu s'affiche 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, qui nous permet d'obtenir des informations utiles sur la boucle en cours :

• $iterator->first – est-ce la première itération ?
• $iterator->last – est-ce la dernière itération ?
• $iterator->counter – compteur d'itérations, à partir de un
• $iterator->counter0 – compteur d'itérations, à 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 qui entoure l'itérateur courant
• $iterator->nextValue – l'élément suivant de la boucle
• $iterator->nextKey – la clé de l'élément suivant de 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 : $iterator->last fonctionne non seulement pour les tableaux, mais aussi quand la boucle parcourt un itérateur général dont le nombre d'éléments n'est pas connu à l'avance.

{first} {last} {sep}

Ces balises s'utilisent à 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… vous devinez ? 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 s'utilisent aussi élégamment comme n:attributs :

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

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

	<hr n:last>
{/foreach}

Le contenu de la balise {sep} est rendu quand l'itération n'est pas la dernière, ce qui convient au rendu de séparateurs, comme les virgules entre les éléments énumérés :

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

C'est plutôt pratique, non ?

{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 les instructions détaillées.

Elle peut aussi remplacer élégamment {first} et {last} de 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>Item #{$i}</span>
{/for}

La balise peut aussi s'écrire comme un n:attribut :

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

{while}

Là encore, nous écrivons la boucle exactement comme en PHP :

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

Ou comme un n:attribut :

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

Une variante avec la condition dans la balise fermante est également possible : elle correspond à la boucle do-while de PHP :

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

{continueIf} {skipIf} {breakIf}

Les balises spéciales {continueIf ?} et {breakIf ?} permettent de piloter n'importe quelle boucle. Elles passent respectivement à l'itération suivante ou terminent la boucle si la condition est remplie :

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

La balise {skipIf} ressemble beaucoup à {continueIf}, mais elle n'incrémente pas $iterator->counter. Cela évite les trous dans la numérotation quand on affiche le compteur et qu'on saute certains éléments. De plus, la clause {else} sera rendue si tous les éléments sont sautés.

<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 d'un template ou d'un bloc lorsqu'une condition est remplie (autrement dit, une “sortie anticipée”).

{exitIf !$messages}

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

Inclusion de templates

{include 'file.latte'}

Voyez aussi {include block} et {embed}

La balise {include} charge et rend le template indiqué. Dans notre cher langage PHP, cela correspond à peu près à :

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

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

Vous pouvez passer des variables au template inclus de cette façon :

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

L'existence d'un template se vérifie avec la fonction hasTemplate().

Le contenu inclus peut être modifié par des filtres. L'exemple suivant supprime tout le HTML et ajuste la casse :

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

Par défaut, l'héritage de templates n'entre pas en jeu ici. Vous pouvez certes utiliser des blocs dans les templates inclus, mais ils ne remplaceront pas les blocs correspondants du template dans lequel ils sont inclus. Voyez les templates inclus comme des parties de pages ou des modules indépendants et isolés. Ce comportement peut être modifié avec le modificateur with blocks :

{include 'template.latte' with blocks}

Le lien entre le nom de fichier indiqué dans la balise et le fichier sur le disque dépend du loader.

{sandbox}

Quand vous incluez un template créé par un utilisateur final, vous devriez envisager de le placer dans un sandbox (plus d'informations dans la documentation du sandbox) :

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

{block}

Voyez aussi {block name}

Les blocs sans nom permettent d'appliquer des filtres à une partie du template. Vous pouvez par exemple appliquer un filtre spaceless pour supprimer les espaces superflus :

{block|spaceless}
<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 survient pendant le rendu du bloc {try}, tout le bloc est abandonné et le rendu se poursuit 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 survient :

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Désolé, les tweets n'ont pas pu être chargés.</p>
{/try}

La balise peut aussi s'écrire comme un n:attribut :

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

Il est également possible de définir son propre gestionnaire d'exceptions, par exemple à des fins de journalisation.

{rollback}

Le bloc {try} peut aussi être interrompu et sauté manuellement avec {rollback}. Vous n'avez ainsi pas à vérifier toutes les données d'entrée à l'avance : c'est seulement pendant le rendu que vous pouvez décider que l'objet ne doit pas être rendu du tout :

{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 façon similaire, mais elle ne crée les variables que si elles n'existent pas. Si une variable existe déjà et contient la valeur null, elle ne sera pas écrasée :

{default $lang = 'en'}

Vous pouvez aussi indiquer les types des 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 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 indiquée, ont automatiquement null pour valeur par défaut. Les types déclarés sont pour l'instant informatifs et Latte ne les vérifie pas.

Les variables autres que celles déclarées ne sont pas passées au template. C'est ce qui la distingue de la balise {default}.

{capture}

Capture la sortie dans une variable :

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

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

Comme toute balise paire, celle-ci peut aussi s'écrire comme un n:attribut :

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

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

Divers

{contentType}

Utilisez cette balise pour indiquer le type de contenu que représente le template. Les possibilités sont :

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

Son usage est important, car elle règle l'échappement sensible au contexte : ce n'est qu'ensuite que Latte peut échapper correctement. Ainsi, {contentType xml} passe en mode XML, {contentType text} désactive complètement l'échappement.

Si le paramètre est un type MIME complet, comme application/xml, l'en-tête HTTP Content-Type est aussi envoyé au navigateur :

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

{debugbreak}

Indique un point où l'exécution du programme s'interrompra. Cela sert au débogage : le programmeur peut inspecter l'environnement d'exécution et vérifier que le code se comporte comme prévu. Elle prend en charge Xdebug. Vous pouvez aussi ajouter une condition qui détermine quand le programme doit s'interrompre.

{debugbreak}                {* interrompt le programme *}

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

{do}

Exécute du code PHP sans rien afficher. Comme pour toutes les autres balises, code PHP signifie une seule expression, voyez Limitations de PHP.

{do $num++}

{dump}

Dumpe une variable ou le contexte courant.

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

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

Nécessite la bibliothèque Tracy.

{php}

Par défaut, {php} fonctionne comme un alias obsolète de {do} et n'évalue qu'une seule expression. Pour exécuter n'importe quel code PHP, la balise doit être activée par l'extension RawPhpExtension.

{spaceless}

Supprime les espaces superflus de la sortie. Elle fonctionne comme le filtre spaceless.

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

Génère :

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

La balise peut aussi s'écrire comme un n:attribut.

{syntax}

Les balises Latte n'ont pas à être encadrées uniquement par de simples accolades. Vous pouvez choisir un autre séparateur, même à l'exécution. Cela se fait avec {syntax …}, dont le paramètre peut être :

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

Avec les n:attributs, vous pouvez par exemple désactiver Latte pour un seul bloc de JavaScript :

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

Latte s'utilise très confortablement à l'intérieur de JavaScript ; évitez seulement les constructions comme dans cet exemple, où une lettre suit immédiatement {, voyez Latte à l'intérieur de JavaScript ou CSS.

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

{trace}

Lève une exception Latte\RuntimeException dont la pile d'appels suit l'esprit des templates. Au lieu d'appels de fonctions et de méthodes, il s'agit donc d'appels de blocs et d'inclusions de templates. Si vous utilisez un outil d'affichage clair des exceptions levées, comme Tracy, vous verrez distinctement la pile d'appels, avec tous les arguments passés.

Aides pour l'intégrateur HTML

n:class

Depuis Latte 3.1, l'attribut HTML class standard a acquis les mêmes fonctionnalités. Vous n'avez donc plus besoin d'utiliser n:class.

Grâce à n:class, il est très facile de générer l'attribut HTML class exactement comme il le faut.

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 j'ai ensuite besoin 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 tous les éléments devraient avoir la classe list-item :

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

Étonnamment simple, non ?

n:attr

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

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

Selon les valeurs retournées, il affiche par exemple :

<input type="checkbox">

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

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

Les fonctionnalités des attributs intelligents de Latte 3.1, comme la suppression des valeurs null ou le passage de tableaux à class ou style, fonctionnent aussi dans n:attr :

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

n:tag

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

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

Si $heading === null, la balise <h1> est affichée sans changement. Sinon, le nom de l'élément devient la valeur de la variable ; pour $heading === 'h3', cela donne donc :

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

Parce que Latte est un système de templates sûr, il vérifie que le nouveau nom de balise est valide et ne contient aucune valeur indésirable ou malveillante.

n:ifcontent

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

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

Selon la valeur de la variable $error, cela affichera :

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

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

Traduction

Pour que les balises de traduction fonctionnent, vous devez activer le traducteur. Vous pouvez aussi utiliser le filtre translate pour traduire.

{_...}

Traduit des valeurs dans d'autres langues.

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

D'autres paramètres peuvent également être passés 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 aussi s'écrire comme un n:attribut, pour traduire l'intérieur de l'élément :

<h1 n:translate>Commande</h1>