Nette Documentation Preview

syntax
Sintaxis
********

.[perex]
Syntax Latte nació de las necesidades prácticas de los diseñadores web. Buscábamos la sintaxis más fácil de usar, con la que poder escribir con elegancia construcciones que de otro modo supondrían un verdadero reto.
Al mismo tiempo, todas las expresiones se escriben exactamente igual que en PHP, por lo que no es necesario aprender un nuevo lenguaje. Sólo tienes que aprovechar al máximo lo que ya sabes.

A continuación se muestra una plantilla mínima que ilustra algunos elementos básicos: etiquetas, n:attributes, comentarios y filtros.

```latte
{* esto es un comentario *}
<ul n:if="$items">                {* n:if es n:atributos *}
{foreach $items as $item}         {* etiqueta que representa el bucle foreach *}
	<li>{$item|capitalize}</li>   {* etiqueta que imprime una variable con un filtro *}
{/foreach}                        {* fin de ciclo *}
</ul>
```

Echemos un vistazo más de cerca a estos importantes elementos y cómo pueden ayudarte a construir una plantilla increíble.


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

Una plantilla contiene etiquetas que controlan la lógica de la plantilla (por ejemplo, bucles *foreach*) o las expresiones de salida. Para ambos, se utiliza un único delimitador `{ ... }`, por lo que no hay que pensar qué delimitador utilizar en cada situación, como ocurre con otros sistemas.
Si el carácter `{` va seguido de una comilla o un espacio, Latte no lo considera el comienzo de una etiqueta, por lo que puede utilizar construcciones JavaScript, JSON o reglas CSS en sus plantillas sin ningún problema.

Ver [resumen de todas las etiquetas |tags]. Además, también puede crear [etiquetas personalizadas |extending-latte#tags].


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

Puedes usar expresiones PHP que conozcas bien dentro de las etiquetas:

- variables
- cadenas (incluyendo HEREDOC y NOWDOC), matrices, números, etc.
- [operadores |https://www.php.net/manual/en/language.operators.php]
- llamadas a funciones y métodos (que pueden estar restringidas por [sandbox])
- [coincidencia |https://www.php.net/manual/en/control-structures.match.php]
- [funciones anónimas |https://www.php.net/manual/en/functions.arrow.php]
- [devoluciones de llamada |https://www.php.net/manual/en/functions.first_class_callable_syntax.php]
- comentarios multilínea `/* ... */`
- etc.

Además, Latte añade varias [buenas extensiones |#Syntactic Sugar] a la sintaxis PHP.


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

Cada etiqueta de par, como `{if} … {/if}`, que opera sobre un único elemento HTML puede escribirse en notación [n:attribute |#n:attribute]. Por ejemplo, `{foreach}` en el ejemplo anterior también podría escribirse de esta manera:

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

La funcionalidad corresponde entonces al elemento HTML en el que está escrita:

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

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

Imprime:

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

Utilizando el prefijo `inner-` podemos alterar el comportamiento para que la funcionalidad se aplique sólo al cuerpo del elemento:

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

Imprime:

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

O utilizando `tag-` prefijo la funcionalidad se aplica en las etiquetas HTML solamente:

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

Dependiendo del valor de la variable `$url` se imprimirá:

```latte
// cuando $url está vacía
<p>Título</p>

// cuando $url es igual a 'https://nette.org'
<p><a href="https://nette.org">Título</a></p>
```

Sin embargo, los atributos n:no son sólo un atajo para las etiquetas de pares, también hay algunos atributos n:puros, por ejemplo el mejor amigo del programador, [n:class |tags#n:class].


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

Consulte el resumen de filtros [estándar |filters].

Latte permite llamar a los filtros utilizando la notación del signo pipa (se permite el espacio precedente):

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

Los filtros pueden encadenarse, en cuyo caso se aplican en orden de izquierda a derecha:

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

Los parámetros se ponen después del nombre del filtro separados por dos puntos o coma:

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

Los filtros se pueden aplicar sobre la expresión:

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

En bloque:

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

O directamente sobre el valor (en combinación con [`{=expr}` | https://latte.nette.org/es/tags#printing] etiqueta):
```latte
<h1>{='  Hello world  '|trim}<h1>
```


Etiquetas HTML dinámicas .[#toc-dynamic-html-tags]
==================================================

Latte soporta etiquetas HTML dinámicas, que son útiles cuando se necesita flexibilidad en los nombres de las etiquetas:

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

Por ejemplo, el código anterior puede generar `<h1>Heading</h1>` o `<h2>Heading</h2>` en función del valor de la variable `$level`. Las etiquetas HTML dinámicas en Latte deben ir siempre emparejadas. Su alternativa es la [n:tag |tags#n:tag].

Como Latte es un sistema de plantillas seguro, comprueba que el nombre de la etiqueta resultante sea válido y no contenga valores no deseados o maliciosos. También se asegura de que el nombre de la etiqueta final sea siempre el mismo que el de la etiqueta inicial.


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

Los comentarios se escriben de esta manera y no entran en la salida:

```latte
{* esto es un comentario en Latte *}
```

Los comentarios PHP funcionan dentro de las etiquetas:

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


Azúcar sintáctico .[#toc-syntactic-sugar]
=========================================


Cadenas sin comillas .[#toc-strings-without-quotation-marks]
------------------------------------------------------------

Las comillas pueden omitirse en las cadenas simples:

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

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

Las cadenas simples son las que están formadas únicamente por letras, cifras, guiones bajos, guiones y puntos. No deben empezar por un dígito ni comenzar o terminar con un guión.
No debe estar compuesto únicamente por letras mayúsculas y guiones bajos, porque entonces se considera una constante (por ejemplo, `PHP_VERSION`).
Y no debe colisionar con las palabras clave `and`, `array`, `clone`, `default`, `false`, `in`, `instanceof`, `new`, `null`, `or`, `return`, `true`, `xor`.


Operador ternario corto .[#toc-short-ternary-operator]
------------------------------------------------------

Si el tercer valor del operador ternario está vacío, puede omitirse:

```latte
como en PHP: {$stock ? 'In stock' : ''}

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


Notación moderna de clave en el array .[#toc-modern-key-notation-in-the-array]
------------------------------------------------------------------------------

Las claves de los arrays pueden escribirse de forma similar a los parámetros con nombre al llamar a funciones:

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

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


Filtros .[#toc-filters]
-----------------------

Los filtros pueden utilizarse para cualquier expresión, basta con encerrar el conjunto entre paréntesis:

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


Operador `in` .[#toc-operator-in]
---------------------------------

El operador `in` puede utilizarse para sustituir a la función `in_array()`. La comparación es siempre estricta:

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


Una ventana a la historia .[#toc-a-window-into-history]
-------------------------------------------------------

Latte ha ideado una serie de caramelos sintácticos a lo largo de su historia, que aparecieron en el propio PHP unos años más tarde. Por ejemplo, en Latte era posible escribir arrays como `[1, 2, 3]` en lugar de `array(1, 2, 3)` o usar el operador nullsafe `$obj?->foo` mucho antes de que fuera posible en el propio PHP. Latte también introdujo el operador de expansión de arrays `(expand) $arr`, que es el equivalente al actual operador `...$arr` de PHP.

El operador undefined-safe `??->`, que es similar al operador nullsafe `?->`, pero no lanza un error si la variable no existe, fue creado por razones históricas y hoy en día recomendamos usar el operador estándar de PHP `?->`.


Limitaciones de PHP en Latte .[#toc-php-limitations-in-latte]
=============================================================

En Latte sólo se pueden escribir expresiones PHP. Es decir, no se pueden utilizar expresiones que terminen en punto y coma. No se pueden declarar clases ni utilizar [estructuras de |https://www.php.net/manual/en/language.control-structures.php] control, como `if`, `foreach`, `switch`, `return`, `try`, `throw` y otras, en lugar de las cuales Latte ofrece sus [etiquetas |tags].
Tampoco puedes usar [atributos |https://www.php.net/manual/en/language.attributes.php], [backticks |https://www.php.net/manual/en/language.operators.execution.php] ni ninguna de las [constantes mágicas |https://www.php.net/manual/en/language.constants.magic.php].
Ni siquiera puede utilizar `unset`, `echo`, `include`, `require`, `exit`, `eval`, porque no son funciones, sino construcciones especiales del lenguaje PHP, y por tanto no son expresiones. Sólo se admiten comentarios multilínea `/* ... */`.

Sin embargo, puede trabajar alrededor de estas limitaciones activando la extensión [RawPhpExtension |develop#RawPhpExtension], que le permite usar cualquier código PHP en la etiqueta `{php ...}` bajo la responsabilidad del autor de la plantilla.

Sintaxis

Syntax Latte nació de las necesidades prácticas de los diseñadores web. Buscábamos la sintaxis más fácil de usar, con la que poder escribir con elegancia construcciones que de otro modo supondrían un verdadero reto. Al mismo tiempo, todas las expresiones se escriben exactamente igual que en PHP, por lo que no es necesario aprender un nuevo lenguaje. Sólo tienes que aprovechar al máximo lo que ya sabes.

A continuación se muestra una plantilla mínima que ilustra algunos elementos básicos: etiquetas, n:attributes, comentarios y filtros.

{* esto es un comentario *}
<ul n:if="$items">                {* n:if es n:atributos *}
{foreach $items as $item}         {* etiqueta que representa el bucle foreach *}
	<li>{$item|capitalize}</li>   {* etiqueta que imprime una variable con un filtro *}
{/foreach}                        {* fin de ciclo *}
</ul>

Echemos un vistazo más de cerca a estos importantes elementos y cómo pueden ayudarte a construir una plantilla increíble.

Tags

Una plantilla contiene etiquetas que controlan la lógica de la plantilla (por ejemplo, bucles foreach) o las expresiones de salida. Para ambos, se utiliza un único delimitador { ... }, por lo que no hay que pensar qué delimitador utilizar en cada situación, como ocurre con otros sistemas. Si el carácter { va seguido de una comilla o un espacio, Latte no lo considera el comienzo de una etiqueta, por lo que puede utilizar construcciones JavaScript, JSON o reglas CSS en sus plantillas sin ningún problema.

Ver resumen de todas las etiquetas. Además, también puede crear etiquetas personalizadas.

Latte entiende PHP

Puedes usar expresiones PHP que conozcas bien dentro de las etiquetas:

Además, Latte añade varias buenas extensiones a la sintaxis PHP.

n:atributos

Cada etiqueta de par, como {if} … {/if}, que opera sobre un único elemento HTML puede escribirse en notación n:attribute. Por ejemplo, {foreach} en el ejemplo anterior también podría escribirse de esta manera:

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

La funcionalidad corresponde entonces al elemento HTML en el que está escrita:

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

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

Imprime:

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

Utilizando el prefijo inner- podemos alterar el comportamiento para que la funcionalidad se aplique sólo al cuerpo del elemento:

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

Imprime:

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

O utilizando tag- prefijo la funcionalidad se aplica en las etiquetas HTML solamente:

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

Dependiendo del valor de la variable $url se imprimirá:

// cuando $url está vacía
<p>Título</p>

// cuando $url es igual a 'https://nette.org'
<p><a href="https://nette.org">Título</a></p>

Sin embargo, los atributos n:no son sólo un atajo para las etiquetas de pares, también hay algunos atributos n:puros, por ejemplo el mejor amigo del programador, n:class.

Filtros

Consulte el resumen de filtros estándar.

Latte permite llamar a los filtros utilizando la notación del signo pipa (se permite el espacio precedente):

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

Los filtros pueden encadenarse, en cuyo caso se aplican en orden de izquierda a derecha:

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

Los parámetros se ponen después del nombre del filtro separados por dos puntos o coma:

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

Los filtros se pueden aplicar sobre la expresión:

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

En bloque:

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

O directamente sobre el valor (en combinación con {=expr} etiqueta):

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

Etiquetas HTML dinámicas

Latte soporta etiquetas HTML dinámicas, que son útiles cuando se necesita flexibilidad en los nombres de las etiquetas:

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

Por ejemplo, el código anterior puede generar <h1>Heading</h1> o <h2>Heading</h2> en función del valor de la variable $level. Las etiquetas HTML dinámicas en Latte deben ir siempre emparejadas. Su alternativa es la n:tag.

Como Latte es un sistema de plantillas seguro, comprueba que el nombre de la etiqueta resultante sea válido y no contenga valores no deseados o maliciosos. También se asegura de que el nombre de la etiqueta final sea siempre el mismo que el de la etiqueta inicial.

Comentarios

Los comentarios se escriben de esta manera y no entran en la salida:

{* esto es un comentario en Latte *}

Los comentarios PHP funcionan dentro de las etiquetas:

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

Azúcar sintáctico

Cadenas sin comillas

Las comillas pueden omitirse en las cadenas simples:

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

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

Las cadenas simples son las que están formadas únicamente por letras, cifras, guiones bajos, guiones y puntos. No deben empezar por un dígito ni comenzar o terminar con un guión. No debe estar compuesto únicamente por letras mayúsculas y guiones bajos, porque entonces se considera una constante (por ejemplo, PHP_VERSION). Y no debe colisionar con las palabras clave and, array, clone, default, false, in, instanceof, new, null, or, return, true, xor.

Operador ternario corto

Si el tercer valor del operador ternario está vacío, puede omitirse:

como en PHP: {$stock ? 'In stock' : ''}

abreviado:   {$stock ? 'In stock'}

Notación moderna de clave en el array

Las claves de los arrays pueden escribirse de forma similar a los parámetros con nombre al llamar a funciones:

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

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

Filtros

Los filtros pueden utilizarse para cualquier expresión, basta con encerrar el conjunto entre paréntesis:

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

Operador in

El operador in puede utilizarse para sustituir a la función in_array(). La comparación es siempre estricta:

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

Una ventana a la historia

Latte ha ideado una serie de caramelos sintácticos a lo largo de su historia, que aparecieron en el propio PHP unos años más tarde. Por ejemplo, en Latte era posible escribir arrays como [1, 2, 3] en lugar de array(1, 2, 3) o usar el operador nullsafe $obj?->foo mucho antes de que fuera posible en el propio PHP. Latte también introdujo el operador de expansión de arrays (expand) $arr, que es el equivalente al actual operador ...$arr de PHP.

El operador undefined-safe ??->, que es similar al operador nullsafe ?->, pero no lanza un error si la variable no existe, fue creado por razones históricas y hoy en día recomendamos usar el operador estándar de PHP ?->.

Limitaciones de PHP en Latte

En Latte sólo se pueden escribir expresiones PHP. Es decir, no se pueden utilizar expresiones que terminen en punto y coma. No se pueden declarar clases ni utilizar estructuras de control, como if, foreach, switch, return, try, throw y otras, en lugar de las cuales Latte ofrece sus etiquetas. Tampoco puedes usar atributos, backticks ni ninguna de las constantes mágicas. Ni siquiera puede utilizar unset, echo, include, require, exit, eval, porque no son funciones, sino construcciones especiales del lenguaje PHP, y por tanto no son expresiones. Sólo se admiten comentarios multilínea /* ... */.

Sin embargo, puede trabajar alrededor de estas limitaciones activando la extensión RawPhpExtension, que le permite usar cualquier código PHP en la etiqueta {php ...} bajo la responsabilidad del autor de la plantilla.