Tags Latte

Visão geral e descrição de todas as tags do sistema de templates Latte que estão disponíveis por padrão.

Exibição

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

No Latte, a tag {=...} é usada para exibir qualquer expressão na saída. O Latte se preocupa com sua conveniência, então se a expressão começa com uma variável ou chamada de função, não é necessário escrever o sinal de igual. O que na prática significa que quase nunca é necessário escrevê-lo:

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

Como expressão, você pode escrever qualquer coisa que conheça do PHP. Você simplesmente não precisa aprender uma nova linguagem. Por exemplo:

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

Por favor, não procure nenhum sentido no exemplo anterior, mas se encontrar algum, escreva para nós :-)

Escaping da saída

Qual é a tarefa mais importante de um sistema de template? Prevenir falhas de segurança. E é exatamente isso que o Latte faz sempre que você exibe algo. Ele escapa automaticamente:

<p>{='one < two'}</p>   {* exibe: '<p>one &lt; two</p>' *}

Para ser preciso, o Latte usa escaping sensível ao contexto, que é algo tão importante e único que dedicamos um capítulo separado a ele.

E se você estiver exibindo conteúdo codificado em HTML de uma fonte confiável? Então, você pode facilmente desativar o escaping:

{$trustedHtmlString|noescape}

O uso incorreto do filtro noescape pode levar à vulnerabilidade XSS! Nunca o use a menos que tenha certeza absoluta do que está fazendo e que a string exibida vem de uma fonte confiável.

Exibição em JavaScript

Graças ao escaping sensível ao contexto, é maravilhosamente fácil exibir variáveis dentro de JavaScript e o Latte cuida do escaping correto.

A variável não precisa ser apenas uma string, qualquer tipo de dados é suportado, que é então codificado como JSON:

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

Gera:

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

Essa também é a razão pela qual não se escrevem aspas em torno da variável: o Latte as adiciona automaticamente para strings. E se você quiser inserir uma variável de string em outra string, simplesmente concatene-as:

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

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

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

Filtros

A expressão exibida pode ser modificada por um filtro. Assim, por exemplo, convertemos uma string para maiúsculas e a encurtamos para um máximo de 30 caracteres:

{$string|upper|truncate:30}

Você também pode aplicar filtros a partes parciais da expressão desta forma:

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

Condições

{if} {elseif} {else}

As condições se comportam da mesma forma que suas contrapartes em PHP. Você pode usar as mesmas expressões nelas que conhece do PHP, não precisa aprender uma nova linguagem.

{if $product->inStock > Stock::Minimum}
	Em estoque
{elseif $product->isOnWay()}
	A caminho
{else}
	Não disponível
{/if}

Como toda tag par, o par {if} ... {/if} também pode ser escrito na forma de um n:atributo, por exemplo:

<p n:if="$count > 0">Em estoque {$count} peças</p>

Você sabia que pode adicionar o prefixo tag- aos n:atributos? Então a condição se aplicará apenas à exibição das tags HTML e o conteúdo entre elas será sempre exibido:

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

{* exibe 'Hello' quando $clickable é falso *}
{* exibe '<a href="...">Hello</a>' quando $clickable é verdadeiro *}

Incrível.

n:else

Se você escrever a condição {if} ... {/if} na forma de um n:atributo, você tem a opção de especificar também um ramo alternativo usando n:else:

<strong n:if="$count > 0">Em estoque {$count} peças</strong>

<em n:else>não disponível</em>

O atributo n:else também pode ser usado em conjunto com n:ifset, n:foreach, n:try, n:ifcontent e n:ifchanged.

{/if $cond}

Você pode se surpreender que a expressão na condição {if} também possa ser especificada na tag de fechamento. Isso é útil em situações em que ainda não conhecemos seu valor ao abrir a condição. Vamos chamar isso de decisão adiada.

Por exemplo, começamos a exibir uma tabela com registros de um banco de dados e só depois de terminar a exibição percebemos que não havia nenhum registro no banco de dados. Então, colocamos uma condição na tag de fechamento {/if} e, se não houver nenhum registro, nada disso será exibido:

{if}
	<h1>Lista de linhas do banco de dados</h1>

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

Engenhoso, não é?

Na condição adiada, também é possível usar {else}, mas não {elseif}.

{ifset} {elseifset}

Veja também {ifset block}

Usando a condição {ifset $var}, verificamos se uma variável (ou mais variáveis) existe e tem um valor não-null. Na verdade, é o mesmo que if (isset($var)) em PHP. Como toda tag par, ela também pode ser escrita na forma de um n:atributo, então vamos mostrar isso como exemplo:

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

{ifchanged}

{ifchanged} verifica se o valor de uma variável mudou desde a última iteração no loop (foreach, for ou while).

Se especificarmos uma ou mais variáveis na tag, ele verificará se alguma delas mudou e exibirá o conteúdo de acordo. Por exemplo, o exemplo a seguir exibe a primeira letra do nome como um título toda vez que ela muda durante a exibição dos nomes:

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

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

No entanto, se não especificarmos nenhum argumento, o conteúdo renderizado será verificado em relação ao seu estado anterior. Isso significa que, no exemplo anterior, podemos omitir o argumento na tag. E, claro, também podemos usar um n:atributo:

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

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

Dentro de {ifchanged}, também é possível especificar uma cláusula {else}.

{switch} {case} {default}

Compara um valor com várias opções. É análogo à instrução condicional switch, que você conhece do PHP. No entanto, o Latte o aprimora:

• usa comparação estrita (===)
• não precisa de break

É, portanto, o equivalente exato da estrutura match que vem com o PHP 8.0.

{switch $transport}
	{case train}
		De trem
	{case plane}
		De avião
	{default}
		Outro
{/switch}

A cláusula {case} pode conter vários valores separados por vírgulas:

{switch $status}
{case $status::New}<b>novo item</b>
{case $status::Sold, $status::Unknown}<i>não disponível</i>
{/switch}

Loops

No Latte, você encontrará todos os loops que conhece do PHP: foreach, for e while.

{foreach}

Escrevemos o loop exatamente como em PHP:

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

Além disso, ele tem alguns truques úteis, sobre os quais falaremos agora.

Por exemplo, o Latte verifica se as variáveis criadas não sobrescrevem acidentalmente variáveis globais com o mesmo nome. Isso salva situações em que você conta que $lang contém o idioma atual da página e não percebe que foreach $langs as $lang sobrescreveu essa variável.

O loop foreach também pode ser escrito de forma muito elegante e econômica usando um n:atributo:

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

Você sabia que pode adicionar o prefixo inner- aos n:atributos? Então, apenas o interior do elemento será repetido no loop:

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

Então, algo como isto será exibido:

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

{else}

Dentro do loop foreach, você pode especificar uma cláusula {else}, cujo conteúdo será exibido se o loop estiver vazio:

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Desculpe, não há usuários nesta lista</em></li>
	{/foreach}
</ul>

$iterator

Dentro do loop foreach, o Latte cria a variável $iterator, com a qual podemos obter informações úteis sobre o loop em andamento:

• $iterator->first – está passando pelo loop pela primeira vez?
• $iterator->last – é a última passagem?
• $iterator->counter – qual é a passagem, contado a partir de um?
• $iterator->counter0 – qual é a passagem, contado a partir de zero?
• $iterator->odd – é uma passagem ímpar?
• $iterator->even – é uma passagem par?
• $iterator->parent – o iterador que envolve o atual
• $iterator->nextValue – o próximo item no loop
• $iterator->nextKey – a chave do próximo item no loop

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

O Latte é esperto e $iterator->last funciona não apenas para arrays, mas também quando o loop ocorre sobre um iterador geral, onde o número de itens não é conhecido antecipadamente.

{first} {last} {sep}

Estas tags podem ser usadas dentro do loop {foreach}. O conteúdo de {first} é renderizado se for a primeira passagem. O conteúdo de {last} é renderizado … você consegue adivinhar? Sim, se for a última passagem. Na verdade, são atalhos para {if $iterator->first} e {if $iterator->last}.

As tags também podem ser usadas elegantemente como um n:atributo:

{foreach $rows as $row}
	{first}<h1>Lista de nomes</h1>{/first}

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

	<hr n:last>
{/foreach}

O conteúdo da tag {sep} é renderizado se a passagem não for a última, sendo útil para renderizar separadores, por exemplo, vírgulas entre os itens exibidos:

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

Isso é bastante prático, não é?

{iterateWhile}

Simplifica o agrupamento de dados lineares durante a iteração em um loop foreach, realizando a iteração em um loop aninhado enquanto a condição for atendida. Leia o tutorial detalhado.

Também pode substituir elegantemente {first} e {last} no exemplo acima:

{foreach $rows as $row}
	<table>

	{iterateWhile}
	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>
	{/iterateWhile true}

	</table>
{/foreach}

Veja também os filtros batch e group.

{for}

Escrevemos o loop exatamente como em PHP:

{for $i = 0; $i < 10; $i++}
	<span>Item {$i}</span>
{/for}

A tag também pode ser usada como um n:atributo:

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

{while}

Novamente, escrevemos o loop exatamente como em PHP:

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

Ou como um n:atributo:

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

Também é possível uma variante com a condição na tag de fechamento, que corresponde ao loop do-while em PHP:

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

{continueIf} {skipIf} {breakIf}

Para controlar qualquer loop, podem ser usadas as tags {continueIf ?} e {breakIf ?}, que passam para o próximo elemento ou encerram o loop, respectivamente, se a condição for atendida:

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

A tag {skipIf} é muito semelhante a {continueIf}, mas não incrementa o contador $iterator->counter, então se o exibirmos e ao mesmo tempo pularmos alguns itens, não haverá lacunas na numeração. E também a cláusula {else} será renderizada se pularmos todos os itens.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>Desculpe, não há adultos nesta lista</em></li>
	{/foreach}
</ul>

{exitIf}

Encerra a renderização do template ou bloco se a condição for atendida (o chamado “early exit”).

{exitIf !$messages}

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

Inclusão de template

{include 'file.latte'}

Veja também {include block}

A tag {include} carrega e renderiza o template especificado. Se estivéssemos falando na linguagem do nosso amado PHP, seria algo como:

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

Os templates incluídos não têm acesso às variáveis do contexto ativo, eles têm acesso apenas às variáveis globais.

Você pode passar variáveis para o template incluído desta forma:

{include 'template.latte', foo: 'bar', id: 123}

O nome do template pode ser qualquer expressão PHP:

{include $someVar}
{include $ajax ? 'ajax.latte' : 'not-ajax.latte'}

O conteúdo incluído pode ser modificado usando filtros. O exemplo a seguir remove todo o HTML e ajusta a capitalização:

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

Por padrão, a herança de templates não desempenha nenhum papel neste caso. Embora possamos usar blocos no template incluído, os blocos correspondentes no template em que ele está sendo incluído não serão substituídos. Pense nos templates incluídos como partes ou módulos isolados e independentes das páginas. Este comportamento pode ser alterado usando o modificador with blocks:

{include 'template.latte' with blocks}

A relação entre o nome do arquivo especificado na tag e o arquivo no disco é assunto do loader.

{sandbox}

Ao incluir um template criado pelo usuário final, você deve considerar o modo sandbox (mais informações na documentação do sandbox):

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

{block}

Veja também {block name}

Blocos sem nome servem como uma maneira de aplicar filtros a uma parte do template. Por exemplo, assim pode ser aplicado o filtro strip, que remove espaços em branco desnecessários:

{block|strip}
<ul>
	<li>Hello World</li>
</ul>
{/block}

Controle de exceções

{try}

Graças a esta tag, é extremamente fácil criar templates robustos.

Se ocorrer uma exceção durante a renderização do bloco {try}, todo o bloco será descartado e a renderização continuará após ele:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
{/try}

O conteúdo na cláusula opcional {else} será renderizado apenas se ocorrer uma exceção:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Desculpe, não foi possível carregar os tweets.</p>
{/try}

A tag também pode ser usada como um n:atributo:

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

Também é possível definir um manipulador de exceções personalizado, por exemplo, para logging.

{rollback}

O bloco {try} também pode ser interrompido e pulado manualmente usando {rollback}. Graças a isso, você não precisa verificar todos os dados de entrada antecipadamente e pode decidir durante a renderização que não deseja renderizar o objeto:

{try}
<ul>
	{foreach $people as $person}
 		{skipIf $person->age < 18}
 		<li>{$person->name}</li>
	{else}
		{rollback}
	{/foreach}
</ul>
{/try}

Variáveis

{var} {default}

Criamos novas variáveis no template com a tag {var}:

{var $name = 'John Smith'}
{var $age = 27}

{* Declaração múltipla *}
{var $name = 'John Smith', $age = 27}

A tag {default} funciona de forma semelhante, mas cria variáveis apenas se elas não existirem. Se a variável já existir e contiver o valor null, ela não será sobrescrita:

{default $lang = 'pt'}

Você também pode especificar tipos de variáveis. Por enquanto, eles são informativos e o Latte não os verifica.

{var string $name = $article->getTitle()}
{default int $id = 0}

{parameters}

Assim como uma função declara seus parâmetros, um template também pode declarar suas variáveis no início:

{parameters
	$a,
	?int $b,
	int|string $c = 10
}

As variáveis $a e $b sem um valor padrão especificado têm automaticamente o valor padrão null. Os tipos declarados são, por enquanto, informativos e o Latte não os verifica.

Outras variáveis além das declaradas não são passadas para o template. Isso difere da tag {default}.

{capture}

Captura a saída para uma variável:

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

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

A tag pode, como toda tag par, ser escrita também como um n:atributo:

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

A saída HTML é armazenada na variável $var na forma de um objeto Latte\Runtime\Html, para que não ocorra escaping indesejado ao ser exibida.

Outros

{contentType}

Com esta tag, você especifica qual tipo de conteúdo o template representa. As opções são:

• html (tipo padrão)
• xml
• javascript
• css
• calendar (iCal)
• text

Seu uso é importante porque define o escaping sensível ao contexto e só assim pode escapar corretamente. Por exemplo, {contentType xml} alterna para o modo XML, {contentType text} desativa completamente o escaping.

Se o parâmetro for um MIME type completo, como application/xml, ele também enviará o cabeçalho HTTP Content-Type para o navegador:

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

{debugbreak}

Marca um local onde a execução do programa será pausada e o debugger será iniciado, para que o programador possa inspecionar o ambiente de execução e verificar se o programa está funcionando como esperado. Suporta Xdebug. É possível adicionar uma condição que determina quando o programa deve ser pausado.

{debugbreak}                {* pausa o programa *}

{debugbreak $counter == 1}  {* pausa o programa se a condição for atendida *}

{do}

Executa código PHP e não exibe nada. Assim como em todas as outras tags, por código PHP entende-se uma única expressão, veja limitações do PHP.

{do $num++}

{dump}

Exibe uma variável ou o contexto atual.

{dump $name} {* Exibe a variável $name *}

{dump}       {* Exibe todas as variáveis atualmente definidas *}

Requer a biblioteca Tracy.

{php}

Permite executar qualquer código PHP. A tag deve ser ativada usando a extensão RawPhpExtension.

{spaceless}

Remove espaços em branco desnecessários da saída. Funciona de forma semelhante ao filtro spaceless.

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

Gera

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

A tag também pode ser escrita como um n:atributo.

{syntax}

As tags Latte não precisam ser delimitadas apenas por chaves simples. Podemos escolher outro delimitador, e até mesmo em tempo de execução. Para isso serve {syntax …}, onde como parâmetro pode ser especificado:

• double: {{...}}
• off: desativa completamente o processamento de tags Latte

Com o uso de n:atributos, é possível desativar o Latte, por exemplo, apenas para um bloco de JavaScript:

<script n:syntax="off">
	var obj = {var: 123}; // isto não é mais uma tag
</script>

O Latte pode ser usado muito convenientemente dentro de JavaScript, basta evitar construções como neste exemplo, onde uma letra segue imediatamente após {, veja Latte dentro de JavaScript ou CSS.

Se você desativar o Latte usando {syntax off} (ou seja, com a tag, não com o n:atributo), ele ignorará consistentemente todas as tags até {/syntax}

{trace}

Lança uma exceção Latte\RuntimeException, cujo stack trace segue o espírito dos templates. Ou seja, em vez de chamadas de funções e métodos, contém chamadas de blocos e inclusões de templates. Se você usa uma ferramenta para exibição clara de exceções lançadas, como Tracy, o call stack será exibido claramente, incluindo todos os argumentos passados.

Auxiliares do codificador HTML

n:class

Graças a n:class, é muito fácil gerar o atributo HTML class exatamente como desejado.

Exemplo: preciso que o elemento ativo tenha a classe active:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active">...</a>
{/foreach}

E, além disso, que o primeiro elemento tenha as classes first e main:

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

E todos os elementos devem ter a classe list-item:

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

Incrivelmente simples, não é?

n:attr

O atributo n:attr pode gerar quaisquer atributos HTML com a mesma elegância que n:class.

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

Dependendo dos valores retornados, exibe por ex.:

<input type="checkbox">

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

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

n:tag

O atributo n:tag pode alterar dinamicamente o nome do elemento HTML.

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

Se $heading === null, a tag <h1> será exibida sem alterações. Caso contrário, o nome do elemento será alterado para o valor da variável, então para $heading === 'h3' será exibido:

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

Como o Latte é um sistema de template seguro, ele verifica se o novo nome da tag é válido e não contém valores indesejados ou maliciosos.

n:ifcontent

Evita que um elemento HTML vazio seja exibido, ou seja, um elemento que não contém nada além de espaços em branco.

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

Exibe dependendo do valor da variável $error:

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

{* $error = 'Obrigatório' *}
<div>
	<div class="error">Obrigatório</div>
</div>

Traduções

Para que as tags de tradução funcionem, é necessário ativar o tradutor. Para tradução, você também pode usar o filtro translate.

{_...}

Traduz valores para outros idiomas.

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

Também é possível passar outros parâmetros para o tradutor:

<a href="basket">{_'Carrinho', domain: order}</a>

{translate}

Traduz partes do template:

<h1>{translate}Pedido{/translate}</h1>

{translate domain: order}Lorem ipsum ...{/translate}

A tag também pode ser escrita como um n:atributo, para traduzir o interior do elemento:

<h1 n:translate>Pedido</h1>