Nette Documentation Preview

syntax
Sintaxe
*******

.[perex]
A sintaxe do Latte nasceu das exigências práticas dos web designers. Estávamos procurando a sintaxe mais fácil de usar, com a qual você pode escrever com elegância construções que de outra forma seriam um verdadeiro desafio.
Ao mesmo tempo, todas as expressões são escritas exatamente da mesma forma que em PHP, para que você não tenha que aprender uma nova linguagem. Você apenas aproveita ao máximo o que já sabe.

Abaixo está um modelo mínimo que ilustra alguns elementos básicos: tags, n:atributos, comentários e filtros.

```latte
{* este é um comentário *}
<ul n:if="$items">                   {* n:se é n:atribut *}
{foreach $items as $item}            {* etiqueta que representa o laço frontal *}
	<li>{$item|capitalize}</li>      {* tag que imprime uma variável com um filtro *}
{/foreach}                           {* final do ciclo *}
</ul>
```

Vamos dar uma olhada mais de perto nestes elementos importantes e como eles podem ajudar você a construir um modelo incrível.


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

Um modelo contém tags que controlam a lógica do modelo (por exemplo, *para cada* laço) ou expressões de saída. Para ambos, é usado um único delimitador `{ ... }`, de modo que não é preciso pensar em qual delimitador usar em qual situação, como acontece com outros sistemas.
Se o caractere `{` for seguido por uma citação ou espaço, Latte não o considera como sendo o início de uma tag, então você pode utilizar construções JavaScript, JSON, ou regras CSS em seus templates sem problemas.

Veja [a visão geral de todas as etiquetas |tags]. Além disso, você também pode criar [etiquetas personalizadas |extending-latte#tags].


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

Você pode usar expressões PHP que você conhece bem dentro das tags:

- variáveis
- cordas (incluindo HEREDOC e NOWDOC), matrizes, números, etc.
- [operadores |https://www.php.net/manual/en/language.operators.php]
- função e chamadas de método (que podem ser restringidas pelo [sandbox |sandbox])
- [jogo |https://www.php.net/manual/en/control-structures.match.php]
- [funções anônimas |https://www.php.net/manual/en/functions.arrow.php]
- [ligações de retorno |https://www.php.net/manual/en/functions.first_class_callable_syntax.php]
- comentários de várias linhas `/* ... */`
- etc....

Além disso, Latte acrescenta várias [extensões agradáveis |#Syntactic Sugar] à sintaxe PHP.


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

Cada tag de par, tal como `{if} … {/if}`, operando sobre um único elemento HTML pode ser escrita em notação de [atributo n:n |#n:attribute]. Por exemplo, `{foreach}` no exemplo acima também poderia ser escrito desta forma:

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

A funcionalidade corresponde então ao elemento HTML em que está escrito:

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

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

Impressões:

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

Usando o prefixo `inner-`, podemos alterar o comportamento para que a funcionalidade se aplique apenas ao corpo do elemento:

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

Impressões:

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

Ou usando o prefixo `tag-`, a funcionalidade é aplicada apenas nas tags HTML:

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

Dependendo do valor da variável `$url`, isto será impresso:

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

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

Entretanto, os n:atributos não são apenas um atalho para etiquetas de pares, existem também alguns n:atributos puros, por exemplo, o melhor amigo do codificador [n:classe |tags#n:class].


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

Veja o resumo dos [filtros padrão |filters].

O Latte permite a chamada de filtros utilizando a notação do sinal de canalização (o espaço precedente é permitido):

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

Os filtros podem ser acorrentados, nesse caso, eles se aplicam por ordem da esquerda para a direita:

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

Os parâmetros são colocados após o nome do filtro separado por dois pontos ou vírgula:

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

Os filtros podem ser aplicados por expressão:

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

Em bloco:

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

Ou diretamente sobre o valor (em combinação com [`{=expr}` | https://latte.nette.org/pt/tags#printing] tag):
```latte
<h1>{='  Hello world  '|trim}<h1>
```


Tags HTML dinâmicas .[#toc-dynamic-html-tags]
=============================================

O Latte oferece suporte a tags HTML dinâmicas, que são úteis quando você precisa de flexibilidade nos nomes das tags:

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

Por exemplo, o código acima pode gerar `<h1>Heading</h1>` ou `<h2>Heading</h2>` dependendo do valor da variável `$level`. As tags HTML dinâmicas no Latte devem ser sempre emparelhadas. Sua alternativa é a [n:tag |tags#n:tag].

Como o Latte é um sistema de modelos seguro, ele verifica se o nome da tag resultante é válido e não contém valores indesejados ou maliciosos. Ele também garante que o nome da tag final seja sempre o mesmo que o nome da tag de abertura.


Comentários .[#toc-comments]
============================

Os comentários são escritos desta forma e não entram na produção:

```latte
{* este é um comentário em Latte *}
```

Os comentários PHP funcionam dentro das tags:

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


Açúcar Syntactic .[#toc-syntactic-sugar]
========================================


Cordas sem marcas de citação .[#toc-strings-without-quotation-marks]
--------------------------------------------------------------------

As aspas podem ser omitidas para cordas simples:

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

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

Cordas simples são aquelas que são compostas puramente de letras, dígitos, sublinhados, hífens e pontos. Elas não devem começar com um dígito e não devem começar ou terminar com um hífen.
Não devem ser compostas apenas de letras maiúsculas e sublinhados, pois então são consideradas uma constante (por exemplo, `PHP_VERSION`).
E não deve colidir com as palavras-chave `and`, `array`, `clone`, `false`, `default`, , `in`, `instanceof`, `new`, `null`, `or`, , `return`, `true`, `xor`.


Operador de Ternary curto .[#toc-short-ternary-operator]
--------------------------------------------------------

Se o terceiro valor do operador ternário estiver vazio, ele pode ser omitido:

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

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


Notação Chave Moderna no Array .[#toc-modern-key-notation-in-the-array]
-----------------------------------------------------------------------

As chaves de matriz podem ser escritas de forma semelhante aos parâmetros nomeados ao chamar funções:

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

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


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

Os filtros podem ser usados para qualquer expressão, basta anexar o todo entre parênteses:

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


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

O operador `in` pode ser usado para substituir a função `in_array()`. A comparação é sempre rigorosa:

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


Uma Janela para a História .[#toc-a-window-into-history]
--------------------------------------------------------

O Latte criou uma série de doces sintáticos ao longo de sua história, que apareceram no próprio PHP alguns anos depois. Por exemplo, em Latte era possível escrever arrays como `[1, 2, 3]` em vez de `array(1, 2, 3)` ou usar o operador nullsafe `$obj?->foo` muito antes de ser possível no próprio PHP. Latte também introduziu o operador de expansão de array `(expand) $arr`, que é o equivalente ao atual operador `...$arr` do PHP.

O operador undefined-safe `??->`, que é semelhante ao operador nullsafe `?->`, mas não gera um erro se a variável não existir, foi criado por motivos históricos e hoje recomendamos o uso do operador padrão do PHP `?->`.


Limitações do PHP em Latte .[#toc-php-limitations-in-latte]
===========================================================

Somente expressões PHP podem ser escritas no Latte. Ou seja, as declarações que terminam com ponto e vírgula não podem ser usadas. Não é possível declarar classes ou usar [estruturas de controle |https://www.php.net/manual/en/language.control-structures.php], como `if`, `foreach`, `switch`, `return`, `try`, `throw` e outras, em vez das quais o Latte oferece suas [tags |tags].
Você também não pode usar [atributos |https://www.php.net/manual/en/language.attributes.php], [backticks |https://www.php.net/manual/en/language.operators.execution.php] ou qualquer uma das [constantes mágicas |https://www.php.net/manual/en/language.constants.magic.php].
Você não pode nem mesmo usar `unset`, `echo`, `include`, `require`, `exit`, `eval`, porque não são funções, mas construções especiais da linguagem PHP e, portanto, não são expressões. Somente comentários de várias linhas são suportados `/* ... */`.

Entretanto, você pode contornar essas limitações ativando a extensão [RawPhpExtension |develop#RawPhpExtension], que permite utilizar qualquer código PHP na tag `{php ...}` sob a responsabilidade do autor do modelo.

Sintaxe

A sintaxe do Latte nasceu das exigências práticas dos web designers. Estávamos procurando a sintaxe mais fácil de usar, com a qual você pode escrever com elegância construções que de outra forma seriam um verdadeiro desafio. Ao mesmo tempo, todas as expressões são escritas exatamente da mesma forma que em PHP, para que você não tenha que aprender uma nova linguagem. Você apenas aproveita ao máximo o que já sabe.

Abaixo está um modelo mínimo que ilustra alguns elementos básicos: tags, n:atributos, comentários e filtros.

{* este é um comentário *}
<ul n:if="$items">                   {* n:se é n:atribut *}
{foreach $items as $item}            {* etiqueta que representa o laço frontal *}
	<li>{$item|capitalize}</li>      {* tag que imprime uma variável com um filtro *}
{/foreach}                           {* final do ciclo *}
</ul>

Vamos dar uma olhada mais de perto nestes elementos importantes e como eles podem ajudar você a construir um modelo incrível.

Etiquetas

Um modelo contém tags que controlam a lógica do modelo (por exemplo, para cada laço) ou expressões de saída. Para ambos, é usado um único delimitador { ... }, de modo que não é preciso pensar em qual delimitador usar em qual situação, como acontece com outros sistemas. Se o caractere { for seguido por uma citação ou espaço, Latte não o considera como sendo o início de uma tag, então você pode utilizar construções JavaScript, JSON, ou regras CSS em seus templates sem problemas.

Veja a visão geral de todas as etiquetas. Além disso, você também pode criar etiquetas personalizadas.

Latte Entende PHP

Você pode usar expressões PHP que você conhece bem dentro das tags:

Além disso, Latte acrescenta várias extensões agradáveis à sintaxe PHP.

n:atributos

Cada tag de par, tal como {if} … {/if}, operando sobre um único elemento HTML pode ser escrita em notação de atributo n:n. Por exemplo, {foreach} no exemplo acima também poderia ser escrito desta forma:

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

A funcionalidade corresponde então ao elemento HTML em que está escrito:

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

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

Impressões:

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

Usando o prefixo inner-, podemos alterar o comportamento para que a funcionalidade se aplique apenas ao corpo do elemento:

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

Impressões:

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

Ou usando o prefixo tag-, a funcionalidade é aplicada apenas nas tags HTML:

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

Dependendo do valor da variável $url, isto será impresso:

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

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

Entretanto, os n:atributos não são apenas um atalho para etiquetas de pares, existem também alguns n:atributos puros, por exemplo, o melhor amigo do codificador n:classe.

Filtros

Veja o resumo dos filtros padrão.

O Latte permite a chamada de filtros utilizando a notação do sinal de canalização (o espaço precedente é permitido):

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

Os filtros podem ser acorrentados, nesse caso, eles se aplicam por ordem da esquerda para a direita:

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

Os parâmetros são colocados após o nome do filtro separado por dois pontos ou vírgula:

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

Os filtros podem ser aplicados por expressão:

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

Em bloco:

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

Ou diretamente sobre o valor (em combinação com {=expr} tag):

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

Tags HTML dinâmicas

O Latte oferece suporte a tags HTML dinâmicas, que são úteis quando você precisa de flexibilidade nos nomes das tags:

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

Por exemplo, o código acima pode gerar <h1>Heading</h1> ou <h2>Heading</h2> dependendo do valor da variável $level. As tags HTML dinâmicas no Latte devem ser sempre emparelhadas. Sua alternativa é a n:tag.

Como o Latte é um sistema de modelos seguro, ele verifica se o nome da tag resultante é válido e não contém valores indesejados ou maliciosos. Ele também garante que o nome da tag final seja sempre o mesmo que o nome da tag de abertura.

Comentários

Os comentários são escritos desta forma e não entram na produção:

{* este é um comentário em Latte *}

Os comentários PHP funcionam dentro das tags:

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

Açúcar Syntactic

Cordas sem marcas de citação

As aspas podem ser omitidas para cordas simples:

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

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

Cordas simples são aquelas que são compostas puramente de letras, dígitos, sublinhados, hífens e pontos. Elas não devem começar com um dígito e não devem começar ou terminar com um hífen. Não devem ser compostas apenas de letras maiúsculas e sublinhados, pois então são consideradas uma constante (por exemplo, PHP_VERSION). E não deve colidir com as palavras-chave and, array, clone, false, default, , in, instanceof, new, null, or, , return, true, xor.

Operador de Ternary curto

Se o terceiro valor do operador ternário estiver vazio, ele pode ser omitido:

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

abbreviated: {$stock ? 'In stock'}

Notação Chave Moderna no Array

As chaves de matriz podem ser escritas de forma semelhante aos parâmetros nomeados ao chamar funções:

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

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

Filtros

Os filtros podem ser usados para qualquer expressão, basta anexar o todo entre parênteses:

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

Operador in

O operador in pode ser usado para substituir a função in_array(). A comparação é sempre rigorosa:

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

Uma Janela para a História

O Latte criou uma série de doces sintáticos ao longo de sua história, que apareceram no próprio PHP alguns anos depois. Por exemplo, em Latte era possível escrever arrays como [1, 2, 3] em vez de array(1, 2, 3) ou usar o operador nullsafe $obj?->foo muito antes de ser possível no próprio PHP. Latte também introduziu o operador de expansão de array (expand) $arr, que é o equivalente ao atual operador ...$arr do PHP.

O operador undefined-safe ??->, que é semelhante ao operador nullsafe ?->, mas não gera um erro se a variável não existir, foi criado por motivos históricos e hoje recomendamos o uso do operador padrão do PHP ?->.

Limitações do PHP em Latte

Somente expressões PHP podem ser escritas no Latte. Ou seja, as declarações que terminam com ponto e vírgula não podem ser usadas. Não é possível declarar classes ou usar estruturas de controle, como if, foreach, switch, return, try, throw e outras, em vez das quais o Latte oferece suas tags. Você também não pode usar atributos, backticks ou qualquer uma das constantes mágicas. Você não pode nem mesmo usar unset, echo, include, require, exit, eval, porque não são funções, mas construções especiais da linguagem PHP e, portanto, não são expressões. Somente comentários de várias linhas são suportados /* ... */.

Entretanto, você pode contornar essas limitações ativando a extensão RawPhpExtension, que permite utilizar qualquer código PHP na tag {php ...} sob a responsabilidade do autor do modelo.