Nette Documentation Preview

syntax 
Syntaxe
*******

.[perex]
Syntax Latte est né des besoins pratiques des concepteurs de sites Web. Nous étions à la recherche de la syntaxe la plus conviviale, avec laquelle vous pouvez écrire de manière élégante des constructions qui représentent autrement un véritable défi.
En même temps, toutes les expressions sont écrites exactement de la même manière qu'en PHP, de sorte que vous n'avez pas à apprendre un nouveau langage. Il suffit de tirer le meilleur parti de ce que l'on connaît déjà.

Vous trouverez ci-dessous un modèle minimal qui illustre quelques éléments de base : balises, n:attributes, commentaires et filtres.

```latte
{* ceci est un commentaire *}
<ul n:if="$items">                {* n:if est n:atribut *}
{foreach $items as $item}         {* tag représentant la boucle foreach *}
	<li>{$item|capitalize}</li>   {* qui imprime une variable avec un filtre *}
{/foreach}                        {* fin du cycle *}
</ul>
```

Examinons de plus près ces éléments importants et comment ils peuvent vous aider à construire un modèle incroyable.


Marqueurs .[#toc-tags]
======================

Un modèle contient des balises qui contrôlent la logique du modèle (par exemple, les boucles *foreach*) ou les expressions de sortie. Les deux utilisent le même délimiteur `{ ... }`, il n'est donc pas nécessaire de se demander quel délimiteur utiliser dans chaque situation, contrairement à d'autres systèmes.
Si le caractère { est suivi d'un guillemet ou d'un espace, Latte ne le considère pas comme le début d'une balise, permettant ainsi l'utilisation sans problème de constructions JavaScript, JSON ou CSS dans les modèles.

Voir l'[aperçu de toutes les balises |tags]. En outre, vous pouvez également créer des [balises personnalisées |extending-latte#tags].


Latte comprend le PHP .[#toc-latte-understands-php]
===================================================

Vous pouvez utiliser des expressions PHP que vous connaissez bien à l'intérieur des balises :

- variables
- chaînes de caractères (y compris HEREDOC et NOWDOC), tableaux, nombres, etc.
- [opérateurs |https://www.php.net/manual/en/language.operators.php]
- les appels de fonctions et de méthodes (qui peuvent être restreints par la [sandbox])
- [correspondance |https://www.php.net/manual/en/control-structures.match.php]
- [fonctions anonymes |https://www.php.net/manual/en/functions.arrow.php]
- les [callbacks |https://www.php.net/manual/en/functions.first_class_callable_syntax.php]
- commentaires multi-lignes `/* ... */`
- etc...

De plus, Latte ajoute plusieurs [extensions |#Syntactic Sugar] à la syntaxe PHP.


n:attributs .[#toc-n-attributes]
================================

Chaque balise de paire, telle que `{if} … {/if}`, opérant sur un seul élément HTML peut être écrite en notation [n:attribut |#n:attribute]. Par exemple, `{foreach}` dans l'exemple ci-dessus pourrait également être écrit de cette façon :

```latte
<ul n:if="$items">
	<li n:foreach="$items as $item">{$item|capitalize}</li>
</ul>
```

La fonctionnalité correspond alors à l'élément HTML dans lequel elle est écrite :

```latte
{var $items = ['I', '♥', 'Latte']}

<p n:foreach="$items as $item">{$item}</p>
```

Imprimés :

```latte
<p>I</p>
<p>♥</p>
<p>Latte</p>
```

En utilisant le préfixe `inner-`, nous pouvons modifier le comportement de sorte que la fonctionnalité s'applique uniquement au corps de l'élément :

```latte
<div n:inner-foreach="$items as $item">
	<p>{$item}</p>
	<hr>
</div>
```

Imprimés :

```latte
<div>
	<p>I</p>
	<hr>
	<p>♥</p>
	<hr>
	<p>Latte</p>
	<hr>
</div>
```

Ou en utilisant le préfixe `tag-` la fonctionnalité est appliquée sur les balises HTML uniquement :

```latte
<p><a href={$url} n:tag-if="$url">Title</a></p>
```

Selon la valeur de la variable `$url`, ceci s'imprimera :

```latte
// when $url is empty
<p>Title</p>

// when $url equals 'https://nette.org'
<p><a href="https://nette.org">Title</a></p>
```

Cependant, les attributs n:ne sont pas seulement un raccourci pour les balises de paire, il existe également des attributs n:purs, par exemple le meilleur ami du codeur, [n:class |tags#n:class].


Filtres .[#toc-filters]
=======================

Voir le résumé des [filtres standard |filters].

Latte permet d'appeler les filtres en utilisant la notation du signe pipe (l'espace précédent est autorisé) :

```latte
<h1>{$heading|upper}</h1>
```

Les filtres peuvent être enchaînés, dans ce cas ils s'appliquent dans l'ordre de gauche à droite :

```latte
<h1>{$heading|lower|capitalize}</h1>
```

Les paramètres sont placés après le nom du filtre, séparés par des deux points ou des virgules :

```latte
<h1>{$heading|truncate:20,''}</h1>
```

Les filtres peuvent être appliqués sur une expression :

```latte
{var $name = ($title|upper) . ($subtitle|lower)}
```

Sur le bloc :

```latte
<h1>{block |lower}{$heading}{/block}</h1>
```

Ou directement sur la valeur (en combinaison avec [`{=expr}` | https://latte.nette.org/fr/tags#printing] tag) :
```latte
<h1>{='  Hello world  '|trim}<h1>
```


Balises HTML dynamiques .[#toc-dynamic-html-tags]
=================================================

Latte supporte les balises HTML dynamiques, qui sont utiles lorsque vous avez besoin de flexibilité dans les noms de balises :

```latte
<h{$level}>Heading</h{$level}>
```

Par exemple, le code ci-dessus peut générer `<h1>Heading</h1>` ou `<h2>Heading</h2>` en fonction de la valeur de la variable `$level`. Les balises HTML dynamiques dans Latte doivent toujours être appariées. Leur alternative est la [balise n:tag |tags#n:tag].

Latte étant un système de création de modèles sécurisé, il vérifie que le nom de balise résultant est valide et ne contient pas de valeurs indésirables ou malveillantes. Il s'assure également que le nom de la balise de fin est toujours le même que le nom de la balise d'ouverture.


Commentaires .[#toc-comments]
=============================

Les commentaires sont écrits de cette façon et n'apparaissent pas dans la sortie :

```latte
{* ceci est un commentaire en Latte *}
```

Les commentaires PHP fonctionnent à l'intérieur des balises :

```latte
{include 'file.info', /* value: 123 */}
```


Le sucre syntaxique .[#toc-syntactic-sugar]
===========================================


Chaînes de caractères sans guillemets .[#toc-strings-without-quotation-marks]
-----------------------------------------------------------------------------

Les guillemets peuvent être omis pour les chaînes de caractères simples :

```latte
as in PHP:   {var $arr = ['hello', 'btn--default', '€']}

abbreviated: {var $arr = [hello, btn--default, €]}
```

Les chaînes de caractères simples sont celles qui sont composées uniquement de lettres, de chiffres, de traits de soulignement, de traits d'union et de points. Elles ne doivent pas commencer par un chiffre et ne doivent pas commencer ou finir par un trait d'union.
Elle ne doit pas être composée uniquement de lettres majuscules et de traits de soulignement, car elle est alors considérée comme une constante (par exemple `PHP_VERSION`).
Et il ne doit pas entrer en collision avec les mots-clés `and`, `array`, `clone`, `default`, `false`, `in`, `instanceof`, `new`, `null`, `or`, `return`, `true`, `xor`.


Opérateur ternaire court .[#toc-short-ternary-operator]
-------------------------------------------------------

Si la troisième valeur de l'opérateur ternaire est vide, elle peut être omise :

```latte
as in PHP:   {$stock ? 'In stock' : ''}

abbreviated: {$stock ? 'In stock'}
```


La notation moderne des clés dans le tableau .[#toc-modern-key-notation-in-the-array]
-------------------------------------------------------------------------------------

Les clés d'un tableau peuvent être écrites de la même manière que les paramètres nommés lors de l'appel de fonctions :

```latte
as in PHP:   {var $arr = ['one' => 'item 1', 'two' => 'item 2']}

modern:      {var $arr = [one: 'item 1', two: 'item 2']}
```


Filtres .[#toc-filters]
-----------------------

Les filtres peuvent être utilisés pour n'importe quelle expression, il suffit de mettre le tout entre parenthèses :

```latte
{var $content = ($text|truncate: 30|upper)}
```


Opérateur `in` .[#toc-operator-in]
----------------------------------

L'opérateur `in` peut être utilisé pour remplacer la fonction `in_array()`. La comparaison est toujours stricte :

```latte
{* comme in_array($item, $items, true) *}
{if $item in $items}
	...
{/if}
```


Une fenêtre dans l'histoire .[#toc-a-window-into-history]
---------------------------------------------------------

Latte a proposé un certain nombre de bonbons syntaxiques au cours de son histoire, qui sont apparus dans PHP lui-même quelques années plus tard. Par exemple, en Latte, il était possible d'écrire les tableaux en tant que `[1, 2, 3]` au lieu de `array(1, 2, 3)` ou d'utiliser l'opérateur nullsafe `$obj?->foo` bien avant que cela ne soit possible en PHP. Latte a également introduit l'opérateur d'expansion de tableau `(expand) $arr`, qui est l'équivalent de l'opérateur `...$arr` de PHP.

L'opérateur undefined-safe `??->`, qui est similaire à l'opérateur nullsafe `?->`, mais qui ne soulève pas d'erreur si la variable n'existe pas, a été créé pour des raisons historiques et nous recommandons aujourd'hui d'utiliser l'opérateur PHP standard `?->`.


Limitations de PHP dans Latte .[#toc-php-limitations-in-latte]
==============================================================

Seules les expressions PHP peuvent être écrites dans Latte. En d'autres termes, les déclarations se terminant par un point-virgule ne peuvent pas être utilisées. Vous ne pouvez pas déclarer des classes ou utiliser des [structures de contrôle |https://www.php.net/manual/en/language.control-structures.php], telles que `if`, `foreach`, `switch`, `return`, `try`, `throw` et autres, au lieu desquelles Latte propose ses [balises |tags].
Vous ne pouvez pas non plus utiliser d'[attributs |https://www.php.net/manual/en/language.attributes.php], de [backticks |https://www.php.net/manual/en/language.operators.execution.php] ou de [constantes magiques |https://www.php.net/manual/en/language.constants.magic.php].
Vous ne pouvez même pas utiliser `unset`, `echo`, `include`, `require`, `exit`, `eval`, car ce ne sont pas des fonctions, mais des constructions spéciales du langage PHP, et donc pas des expressions. Seuls les commentaires sur plusieurs lignes sont supportés `/* ... */`.

Toutefois, vous pouvez contourner ces limitations en activant l'extension [RawPhpExtension |develop#RawPhpExtension], qui vous permet d'utiliser n'importe quel code PHP dans la balise `{php ...}`, sous la responsabilité de l'auteur du modèle.

Syntaxe

Syntax Latte est né des besoins pratiques des concepteurs de sites Web. Nous étions à la recherche de la syntaxe la plus conviviale, avec laquelle vous pouvez écrire de manière élégante des constructions qui représentent autrement un véritable défi. En même temps, toutes les expressions sont écrites exactement de la même manière qu'en PHP, de sorte que vous n'avez pas à apprendre un nouveau langage. Il suffit de tirer le meilleur parti de ce que l'on connaît déjà.

Vous trouverez ci-dessous un modèle minimal qui illustre quelques éléments de base : balises, n:attributes, commentaires et filtres.

{* ceci est un commentaire *}
<ul n:if="$items">                {* n:if est n:atribut *}
{foreach $items as $item}         {* tag représentant la boucle foreach *}
	<li>{$item|capitalize}</li>   {* qui imprime une variable avec un filtre *}
{/foreach}                        {* fin du cycle *}
</ul>

Examinons de plus près ces éléments importants et comment ils peuvent vous aider à construire un modèle incroyable.

Marqueurs

Un modèle contient des balises qui contrôlent la logique du modèle (par exemple, les boucles foreach) ou les expressions de sortie. Les deux utilisent le même délimiteur { ... }, il n'est donc pas nécessaire de se demander quel délimiteur utiliser dans chaque situation, contrairement à d'autres systèmes. Si le caractère { est suivi d'un guillemet ou d'un espace, Latte ne le considère pas comme le début d'une balise, permettant ainsi l'utilisation sans problème de constructions JavaScript, JSON ou CSS dans les modèles.

Voir l'aperçu de toutes les balises. En outre, vous pouvez également créer des balises personnalisées.

Latte comprend le PHP

Vous pouvez utiliser des expressions PHP que vous connaissez bien à l'intérieur des balises :

De plus, Latte ajoute plusieurs extensions à la syntaxe PHP.

n:attributs

Chaque balise de paire, telle que {if} … {/if}, opérant sur un seul élément HTML peut être écrite en notation n:attribut. Par exemple, {foreach} dans l'exemple ci-dessus pourrait également être écrit de cette façon :

<ul n:if="$items">
	<li n:foreach="$items as $item">{$item|capitalize}</li>
</ul>

La fonctionnalité correspond alors à l'élément HTML dans lequel elle est écrite :

{var $items = ['I', '♥', 'Latte']}

<p n:foreach="$items as $item">{$item}</p>

Imprimés :

<p>I</p>
<p>♥</p>
<p>Latte</p>

En utilisant le préfixe inner-, nous pouvons modifier le comportement de sorte que la fonctionnalité s'applique uniquement au corps de l'élément :

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

Imprimés :

<div>
	<p>I</p>
	<hr>
	<p>♥</p>
	<hr>
	<p>Latte</p>
	<hr>
</div>

Ou en utilisant le préfixe tag- la fonctionnalité est appliquée sur les balises HTML uniquement :

<p><a href={$url} n:tag-if="$url">Title</a></p>

Selon la valeur de la variable $url, ceci s'imprimera :

// when $url is empty
<p>Title</p>

// when $url equals 'https://nette.org'
<p><a href="https://nette.org">Title</a></p>

Cependant, les attributs n:ne sont pas seulement un raccourci pour les balises de paire, il existe également des attributs n:purs, par exemple le meilleur ami du codeur, n:class.

Filtres

Voir le résumé des filtres standard.

Latte permet d'appeler les filtres en utilisant la notation du signe pipe (l'espace précédent est autorisé) :

<h1>{$heading|upper}</h1>

Les filtres peuvent être enchaînés, dans ce cas ils s'appliquent dans l'ordre de gauche à droite :

<h1>{$heading|lower|capitalize}</h1>

Les paramètres sont placés après le nom du filtre, séparés par des deux points ou des virgules :

<h1>{$heading|truncate:20,''}</h1>

Les filtres peuvent être appliqués sur une expression :

{var $name = ($title|upper) . ($subtitle|lower)}

Sur le bloc :

<h1>{block |lower}{$heading}{/block}</h1>

Ou directement sur la valeur (en combinaison avec {=expr} tag) :

<h1>{='  Hello world  '|trim}<h1>

Balises HTML dynamiques

Latte supporte les balises HTML dynamiques, qui sont utiles lorsque vous avez besoin de flexibilité dans les noms de balises :

<h{$level}>Heading</h{$level}>

Par exemple, le code ci-dessus peut générer <h1>Heading</h1> ou <h2>Heading</h2> en fonction de la valeur de la variable $level. Les balises HTML dynamiques dans Latte doivent toujours être appariées. Leur alternative est la balise n:tag.

Latte étant un système de création de modèles sécurisé, il vérifie que le nom de balise résultant est valide et ne contient pas de valeurs indésirables ou malveillantes. Il s'assure également que le nom de la balise de fin est toujours le même que le nom de la balise d'ouverture.

Commentaires

Les commentaires sont écrits de cette façon et n'apparaissent pas dans la sortie :

{* ceci est un commentaire en Latte *}

Les commentaires PHP fonctionnent à l'intérieur des balises :

{include 'file.info', /* value: 123 */}

Le sucre syntaxique

Chaînes de caractères sans guillemets

Les guillemets peuvent être omis pour les chaînes de caractères simples :

as in PHP:   {var $arr = ['hello', 'btn--default', '€']}

abbreviated: {var $arr = [hello, btn--default, €]}

Les chaînes de caractères simples sont celles qui sont composées uniquement de lettres, de chiffres, de traits de soulignement, de traits d'union et de points. Elles ne doivent pas commencer par un chiffre et ne doivent pas commencer ou finir par un trait d'union. Elle ne doit pas être composée uniquement de lettres majuscules et de traits de soulignement, car elle est alors considérée comme une constante (par exemple PHP_VERSION). Et il ne doit pas entrer en collision avec les mots-clés and, array, clone, default, false, in, instanceof, new, null, or, return, true, xor.

Opérateur ternaire court

Si la troisième valeur de l'opérateur ternaire est vide, elle peut être omise :

as in PHP:   {$stock ? 'In stock' : ''}

abbreviated: {$stock ? 'In stock'}

La notation moderne des clés dans le tableau

Les clés d'un tableau peuvent être écrites de la même manière que les paramètres nommés lors de l'appel de fonctions :

as in PHP:   {var $arr = ['one' => 'item 1', 'two' => 'item 2']}

modern:      {var $arr = [one: 'item 1', two: 'item 2']}

Filtres

Les filtres peuvent être utilisés pour n'importe quelle expression, il suffit de mettre le tout entre parenthèses :

{var $content = ($text|truncate: 30|upper)}

Opérateur in

L'opérateur in peut être utilisé pour remplacer la fonction in_array(). La comparaison est toujours stricte :

{* comme in_array($item, $items, true) *}
{if $item in $items}
	...
{/if}

Une fenêtre dans l'histoire

Latte a proposé un certain nombre de bonbons syntaxiques au cours de son histoire, qui sont apparus dans PHP lui-même quelques années plus tard. Par exemple, en Latte, il était possible d'écrire les tableaux en tant que [1, 2, 3] au lieu de array(1, 2, 3) ou d'utiliser l'opérateur nullsafe $obj?->foo bien avant que cela ne soit possible en PHP. Latte a également introduit l'opérateur d'expansion de tableau (expand) $arr, qui est l'équivalent de l'opérateur ...$arr de PHP.

L'opérateur undefined-safe ??->, qui est similaire à l'opérateur nullsafe ?->, mais qui ne soulève pas d'erreur si la variable n'existe pas, a été créé pour des raisons historiques et nous recommandons aujourd'hui d'utiliser l'opérateur PHP standard ?->.

Limitations de PHP dans Latte

Seules les expressions PHP peuvent être écrites dans Latte. En d'autres termes, les déclarations se terminant par un point-virgule ne peuvent pas être utilisées. Vous ne pouvez pas déclarer des classes ou utiliser des structures de contrôle, telles que if, foreach, switch, return, try, throw et autres, au lieu desquelles Latte propose ses balises. Vous ne pouvez pas non plus utiliser d'attributs, de backticks ou de constantes magiques. Vous ne pouvez même pas utiliser unset, echo, include, require, exit, eval, car ce ne sont pas des fonctions, mais des constructions spéciales du langage PHP, et donc pas des expressions. Seuls les commentaires sur plusieurs lignes sont supportés /* ... */.

Toutefois, vous pouvez contourner ces limitations en activant l'extension RawPhpExtension, qui vous permet d'utiliser n'importe quel code PHP dans la balise {php ...}, sous la responsabilité de l'auteur du modèle.