Sintaxe
A sintaxe do Latte surgiu das necessidades práticas dos web designers. Buscamos a sintaxe mais amigável, com a qual pode escrever elegantemente até mesmo construções que, de outra forma, representam um verdadeiro desafio. Ao mesmo tempo, todas as expressões são escritas exatamente como em PHP, então não precisa de aprender uma nova linguagem. Simplesmente aproveita o que já sabe há muito tempo.
Abaixo está um template mínimo que ilustra vários elementos básicos: tags, n:atributos, comentários e filtros.
{* este é um comentário em Latte *}
<ul n:if=$items> {* n:if é um n:atributo *}
{foreach $items as $item} {* tag representando o ciclo foreach *}
<li>{$item|capitalize}</li> {* tag exibindo variável com filtro *}
{/foreach} {* fim do ciclo *}
</ul>
Vamos dar uma olhada mais de perto nesses elementos importantes e como eles podem ajudá-lo a criar um template incrível.
Tags
O template contém tags que controlam a lógica do template (por exemplo, loops foreach) ou exibem expressões. Para
ambos, é usado um único delimitador { ... }
, então não precisa de pensar qual delimitador usar em qual
situação, como é o caso em outros sistemas. Se o caractere {
for seguido por aspas ou espaço, o Latte não
o considera o início de uma tag, graças ao qual pode usar construções JavaScript, JSON ou regras CSS nos seus templates sem
problemas.
Veja a visão geral de todas as tags. Além disso, também pode criar as suas tags personalizadas.
Latte entende PHP
Dentro das tags, pode usar expressões PHP que conhece bem:
- variáveis
- strings (incluindo HEREDOC e NOWDOC), arrays, números, etc.
- operadores
- chamadas de funções e métodos (que podem ser restringidas pelo sandbox)
- match
- funções anónimas
- callbacks
- comentários de múltiplas linhas
/* ... */
- etc…
Além disso, o Latte complementa a sintaxe do PHP com várias extensões agradáveis.
n:atributos
Todas as tags pares, como {if} … {/if}
, operando sobre um único elemento HTML, podem ser reescritas na forma de
n:atributos. Assim, seria possível escrever, por exemplo, o {foreach}
no exemplo inicial:
<ul n:if=$items>
<li n:foreach="$items as $item">{$item|capitalize}</li>
</ul>
A funcionalidade então aplica-se ao elemento HTML em que está localizada:
{var $items = ['I', '♥', 'Latte']}
<p n:foreach="$items as $item">{$item}</p>
exibe:
<p>I</p>
<p>♥</p>
<p>Latte</p>
Usando o prefixo inner-
, podemos modificar o comportamento para que ele se aplique apenas à parte interna do
elemento:
<div n:inner-foreach="$items as $item">
<p>{$item}</p>
<hr>
</div>
Será exibido:
<div>
<p>I</p>
<hr>
<p>♥</p>
<hr>
<p>Latte</p>
<hr>
</div>
Ou usando o prefixo tag-
, aplicamos a funcionalidade apenas às próprias tags HTML:
<p><a href={$url} n:tag-if="$url">Title</a></p>
O que exibe dependendo da variável $url
:
{* quando $url está vazio *}
<p>Title</p>
{* quando $url contém 'https://nette.org' *}
<p><a href="https://nette.org">Title</a></p>
No entanto, os n:atributos não são apenas um atalho para tags pares. Existem também n:atributos puros, como n:href ou o muito útil auxiliar do codificador n:class.
Filtros
Veja a visão geral dos filtros padrão.
Os filtros são escritos após uma barra vertical (pode haver um espaço antes dela):
<h1>{$heading|upper}</h1>
Os filtros podem ser encadeados e são aplicados na ordem da esquerda para a direita:
<h1>{$heading|lower|capitalize}</h1>
Os parâmetros são inseridos após o nome do filtro, separados por dois pontos ou vírgulas:
<h1>{$heading|truncate:20,''}</h1>
Os filtros também podem ser aplicados a uma expressão:
{var $name = ($title|upper) . ($subtitle|lower)}
Num bloco:
<h1>{block |lower}{$heading}{/block}</h1>
Ou diretamente no valor (em combinação com a tag {=expr}
):
<h1>{=' Hello world '|trim}<h1>
Tags HTML dinâmicas
O Latte suporta tags HTML dinâmicas, que são úteis quando precisa de flexibilidade nos nomes das tags:
<h{$level}>Heading</h{$level}>
O código acima pode, por exemplo, 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 pares. A sua alternativa é n:tag.
Como o Latte é um sistema de template seguro, ele verifica se o nome da tag resultante é válido e não contém valores indesejados ou maliciosos. Além disso, garante que o nome da tag de fechamento seja sempre o mesmo que o nome da tag de abertura.
Comentários
Os comentários são escritos desta forma e não aparecem na saída:
{* este é um comentário em Latte *}
Dentro das tags, os comentários PHP funcionam:
{include 'file.info', /* value: 123 */}
Açúcar sintático
Strings sem aspas
Para strings simples, as aspas podem ser omitidas:
como em PHP: {var $arr = ['hello', 'btn--default', '€']}
abreviado: {var $arr = [hello, btn--default, €]}
Strings simples são aquelas compostas puramente por letras, dígitos, sublinhados, hífens e pontos. 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 por letras maiúsculas e sublinhados,
porque então são consideradas constantes (por exemplo, PHP_VERSION
). E não devem colidir com palavras-chave:
and
, array
, clone
, default
, false
, in
,
instanceof
, new
, null
, or
, return
, true
,
xor
.
Constantes
Como é possível omitir aspas em strings simples, recomendamos escrever constantes globais com uma barra no início para diferenciação:
{if \PROJECT_ID === 1} ... {/if}
Esta notação é totalmente válida no próprio PHP, a barra diz que a constante está no namespace global.
Operador ternário abreviado
Se o terceiro valor do operador ternário estiver vazio, ele pode ser omitido:
como em PHP: {$stock ? 'Em estoque' : ''}
abreviado: {$stock ? 'Em estoque'}
Notação moderna de chaves em arrays
As chaves em arrays podem ser escritas de forma semelhante aos parâmetros nomeados ao chamar funções:
como em PHP: {var $arr = ['one' => 'item 1', 'two' => 'item 2']}
moderno: {var $arr = [one: 'item 1', two: 'item 2']}
Filtros
Os filtros podem ser usados para quaisquer expressões, basta envolver o todo em parênteses:
{var $content = ($text|truncate: 30|upper)}
Operador in
O operador in
pode substituir a função in_array()
. A comparação é sempre estrita:
{* análogo a in_array($item, $items, true) *}
{if $item in $items}
...
{/if}
Janela histórica
O Latte introduziu ao longo da sua história uma série de açúcares sintáticos que, após alguns anos, apareceram no
próprio PHP. Por exemplo, no 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.
O Latte também introduziu o operador para desempacotar array (expand) $arr
, que é o equivalente ao operador
atual ...$arr
do PHP.
O operador undefined-safe ??->
, que é análogo ao operador nullsafe ?->
, mas não gera erro
se a variável não existir, surgiu por razões históricas e hoje recomendamos usar o operador PHP padrão
?->
.
Limitações do PHP no Latte
No Latte, apenas expressões PHP podem ser escritas. Ou seja, não é possível usar instruções terminadas em ponto e
vírgula. Não é possível declarar classes ou usar estruturas de controlo, por exemplo, if
,
foreach
, switch
, return
, try
, throw
e outras, para as quais
o Latte oferece as suas tags. Também não é possível usar atributos, backticks ou algumas constantes mágicas. Também não é possível usar
unset
, echo
, include
, require
, exit
, eval
, porque
não são funções, mas construções especiais da linguagem PHP, e não são, portanto, expressões. Os comentários são
suportados apenas em múltiplas linhas /* ... */
.
No entanto, essas limitações podem ser contornadas ativando a extensão RawPhpExtension, graças à qual é possível usar qualquer
código PHP na tag {php ...}
sob a responsabilidade do autor do template.