Latte Tags

Resumo e descrição de todas as etiquetas incorporadas no Latte.

Impressão

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

Latte usa a tag {=...} para imprimir qualquer expressão para a saída. Se a expressão começa com uma variável ou chamada de função, não há necessidade de escrever um sinal de igual. O que, na prática, significa que quase nunca precisa ser escrito:

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

Você pode escrever qualquer coisa que você conhece do PHP como uma expressão. Você simplesmente não precisa aprender uma nova linguagem. Por exemplo, não é preciso aprender uma nova linguagem:

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

Por favor, não procure nenhum significado no exemplo anterior, mas se você encontrar um lá, escreva-nos :-)

Escapando da saída

Qual é a tarefa mais importante de um sistema modelo? Evitar buracos na segurança. E é exatamente isso que Latte faz sempre que você imprime algo para produzir. Ele escapa automaticamente de tudo:

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

Para ser mais preciso, Latte utiliza o escape sensível ao contexto, que é uma característica tão importante e única que lhe dedicamos um capítulo à parte.

E se você imprimir conteúdo codificado em HTML a partir de uma fonte confiável? Então, você pode facilmente desativar a fuga:

{$trustedHtmlString|noescape}

O mau uso do filtro noescape pode levar a uma vulnerabilidade XSS! Nunca o use a menos que você esteja absolutamente seguro do que está fazendo e que o fio que você está imprimindo vem de uma fonte confiável.

Impressão em JavaScript

Graças à fuga sensível ao contexto, é maravilhosamente fácil imprimir variáveis dentro do JavaScript, e o Latte escapará delas adequadamente.

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

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

Gera:

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

Esta é também a razão pela qual **não colocar variável entre aspas***: Latte as adiciona em torno de cordas. E se você quiser colocar uma variável de string em outra string, basta concatená-las:

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

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

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

Filtros

A expressão impressa pode ser modificada por filtros. Por exemplo, este exemplo converte a corda em maiúsculas e a encurta para um máximo de 30 caracteres:

{$string|upper|truncate:30}

Você também pode aplicar filtros a partes de uma expressão como a seguir:

{$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 que você conhece do PHP, você não precisa aprender uma nova linguagem.

{if $product->inStock > Stock::Minimum}
	In stock
{elseif $product->isOnWay()}
	On the way
{else}
	Not available
{/if}

Como qualquer tag de par, um par de {if} ... {/ if} pode ser escrito como n:atributo, por exemplo:

<p n:if="$count > 0">In stock {$count} items</p>

Você sabe que pode adicionar o prefixo tag- aos n:attributes? Então a condição afetará apenas as tags HTML e o conteúdo entre elas será sempre impresso:

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

{* prints 'Hello' when $clickable is falsey *}
{* prints '<a href="...">Hello</a>' when $clickable is truthy *}

Legal.

n:else

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

<strong n:if="$count > 0">In stock {$count} items</strong>

<em n:else>not available</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 etiqueta final. Isto é útil em situações em que ainda não sabemos o valor da condição quando a tag é aberta. Vamos chamar isso de decisão adiada.

Por exemplo, começamos a listar uma tabela com registros do banco de dados, e somente após completar o relatório é que percebemos que não havia nenhum registro no banco de dados. Portanto, colocamos condição na etiqueta final {/if} e, se não houver nenhum registro, nenhum deles será impresso:

{if}
	<h1>Printing rows from the database</h1>

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

Prático, não é?

Você também pode usar {else} na condição diferida, mas não {elseif}.

{ifset} {elseifset}

Veja também {ifset block}

Use a condição {ifset $var} para determinar se uma variável (ou múltiplas variáveis) existe e tem um valor não-nulo. Na verdade é o mesmo que if (isset($var)) em PHP. Como qualquer tag de par, isto pode ser escrito na forma de n:atributo, então vamos mostrá-lo no 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 laço (foreach, para, ou enquanto).

Se especificarmos uma ou mais variáveis na etiqueta, ela verificará se alguma delas mudou e imprimirá o conteúdo de acordo. Por exemplo, o exemplo seguinte imprime a primeira letra de um nome como um título cada vez que ele muda ao listar nomes:

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

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

Entretanto, se nenhum argumento for apresentado, o próprio conteúdo apresentado será verificado em relação ao seu estado anterior. Isto significa que, no exemplo anterior, podemos omitir com segurança o argumento na etiqueta. E é claro que também podemos usar n:attribute:

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

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

Você também pode incluir uma cláusula {else} dentro do {ifchanged}.

{switch} {case} {default}

Compara valor com múltiplas opções. Isto é similar à estrutura switch que você conhece do PHP. No entanto, o Latte o melhora:

• utiliza comparação rigorosa (===)
• não precisa de um break

Portanto, é o equivalente exato da estrutura match que o PHP 8.0 vem com.

{switch $transport}
	{case train}
		By train
	{case plane}
		By plane
	{default}
		Differently
{/switch}

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

{switch $status}
{case $status::New}<b>new item</b>
{case $status::Sold, $status::Unknown}<i>not available</i>
{/switch}

Laços

Em Latte, todos os loops que você conhece do PHP estão disponíveis para você: foreach, for and while.

{foreach}

Você escreve o ciclo exatamente da mesma forma que em PHP:

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

Além disso, ele tem alguns ajustes úteis de que falaremos agora.

Por exemplo, as verificações Latte que criaram variáveis não sobrepõem acidentalmente variáveis globais com o mesmo nome. Isto o salvará quando você assumir que $lang é o idioma atual da página, e não perceber que foreach $langs as $lang sobregravou essa variável.

O laço frontal também pode ser escrito de forma muito elegante e econômica com n:attribute:

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

Você sabia que você pode preender o prefixo inner- para n:attributes? Agora, apenas a parte interna do elemento será repetida no laço:

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

Portanto, imprime algo como:

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

{else}

O laço foreach pode levar uma cláusula opcional {else} cujo texto é exibido se o conjunto dado estiver vazio:

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Sorry, no users in this list</em></li>
	{/foreach}
</ul>

$iterator

Dentro do laço foreach, a variável $iterator é inicializada. Ela contém informações importantes sobre o laço atual.

• $iterator->first – esta é a primeira iteração?
• $iterator->last – esta é a última iteração?
• $iterator->counter – contador de iteração, a partir de 1
• $iterator->counter0 – contador de iteração, a partir de 0
• $iterator->odd – esta iteração é estranha?
• $iterator->even – esta iteração é uniforme?
• $iterator->parent – o iterador que envolve o atual
• $iterator->nextValue – o próximo item do laço
• $iterator->nextKey – a chave do próximo item do laço

{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 é inteligente e $iterator->last funciona não apenas para arrays, mas também quando o laço passa por cima de um iterador geral onde o número de itens não é conhecido antecipadamente.

{first} {last} {sep}

Estas etiquetas podem ser usadas dentro do laço {foreach}. O conteúdo de {first} é apresentado para o primeiro passe. O conteúdo de {last} é renderizado … você pode adivinhar? Sim, para o último passe. Na verdade, estes são atalhos para {if $iterator->first} e {if $iterator->last}.

As etiquetas também podem ser escritas como n:atributos:

{foreach $rows as $row}
	{first}<h1>List of names</h1>{/first}

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

	<hr n:last>
{/foreach}

O conteúdo do {sep} é apresentado se a iteração não for a última, portanto é adequado para a impressão de delimitadores, tais como vírgulas entre os itens listados:

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

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

{iterateWhile}

Ele simplifica o agrupamento de dados lineares durante a iteração em um laço frontal, realizando a iteração em um laço aninhado, desde que a condição seja atendida. Leia as instruções no livro de receitas.

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}

{for}

Nós escrevemos o ciclo exatamente da mesma forma que em PHP:

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

A etiqueta também pode ser escrita como n:atributo:

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

{while}

Novamente, nós escrevemos o ciclo exatamente da mesma forma que em PHP:

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

Ou como n:atributo:

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

Uma variante com uma condição na etiqueta final corresponde ao loop do do-while em PHP:

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

{continueIf} {skipIf} {breakIf}

Há etiquetas especiais que você pode usar para controlar qualquer laço – {continueIf ?} e {breakIf ?} que saltam para a próxima iteração e terminam o laço, respectivamente, se as condições forem cumpridas:

{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. Portanto, não há furos na numeração quando você imprime $iterator->counter e pula alguns itens. Também a cláusula {else} será apresentada quando você pular todos os itens.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>Sorry, no adult users in this list</em></li>
	{/foreach}
</ul>

{exitIf}

Termina a renderização de um modelo ou bloco quando uma condição é atendida (isto é, “saída antecipada”).

{exitIf !$messages}

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

Incluindo os modelos

{include 'file.latte'}

Veja também {include block}

A tag {include} carrega e torna o modelo especificado. Em nossa linguagem PHP favorita, é como:

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

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

Você pode passar variáveis para o modelo inserido da seguinte maneira:

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

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

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

O conteúdo inserido pode ser modificado usando filtros. O exemplo a seguir remove todo o material HTML e ajusta o estojo:

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

A herança do modelo não está envolvida nisso por padrão. Embora você possa adicionar tags de bloco aos modelos incluídos, elas não substituirão os blocos correspondentes no modelo em que foram incluídas. Pense nas inclusões como partes independentes e protegidas de páginas ou módulos. Esse comportamento pode ser alterado usando o modificador with blocks:

{include 'template.latte' with blocks}

A relação entre o nome do arquivo especificado na etiqueta e o arquivo em disco é uma questão de carregador.

{sandbox}

Ao incluir um modelo criado por um usuário final, você deve considerar o sandboxing (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 para a capacidade de aplicar filtros a uma parte do modelo. Por exemplo, você pode aplicar um filtro de tira para remover espaços desnecessários:

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

Tratamento de Exceções

{try}

Estas etiquetas tornam extremamente fácil a construção de modelos robustos.

Se ocorrer uma exceção durante a renderização do bloco {try}, o bloco inteiro é jogado fora e a renderização continuará depois dele:

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

O conteúdo da cláusula opcional {else} é apresentado somente quando ocorre uma exceção:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Sorry, the tweets could not be loaded.</p>
{/try}

A etiqueta também pode ser escrita como n:atributo:

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

Também é possível definir o próprio manipulador de exceções, ou seja, a extração de madeira:

{rollback}

O bloco {try} também pode ser parado e pulado manualmente usando {rollback}. Assim, não é necessário verificar todos os dados de entrada com antecedência, e somente durante a renderização você pode decidir se faz sentido 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}

Vamos criar novas variáveis no modelo 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, exceto que ela só cria variáveis se elas não existirem:

{default $lang = 'cs'}

Você também pode especificar tipos de variáveis. Por enquanto, elas são informativas e o Latte não as verifica.

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

{parameters}

Assim como uma função declara seus parâmetros, um modelo pode declarar suas variáveis em seu início:

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

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

Além das variáveis declaradas, não são passadas para o modelo. Esta é uma diferença em relação à tag {default}.

{capture}

Ao usar a tag {capture} você pode capturar a saída para uma variável:

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

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

A tag também pode ser escrita como n:attribute, como qualquer tag em pares:

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

A saída HTML é armazenada na variável $var como um objeto Latte\Runtime\Html para evitar escapes indesejados durante a impressão.

Outros

{contentType}

Use a etiqueta para especificar que tipo de conteúdo o modelo representa. As opções são:

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

Seu uso é importante porque define a fuga sensível ao contexto e só então o Latte pode escapar corretamente. Por exemplo, {contentType xml} muda para o modo XML, {contentType text} desliga completamente a fuga.

Se o parâmetro for um tipo MIME completo, como application/xml, ele também envia um 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}

Especifica o local onde a execução do código irá quebrar. É usado para fins de depuração para o programador inspecionar o ambiente de tempo de execução e para garantir que o código seja executado conforme o esperado. Ele suporta Xdebug. Além disso, é possível especificar uma condição quando o código deve quebrar.

{debugbreak}                {Quebra o programa *}

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

{do}

Executa o código PHP e não imprime nada. Como em todas as outras tags, o código PHP é uma única expressão; consulte Limitações do PHP.

{do $num++}

{dump}

Despeja um contexto variável ou atual.

{dump $name} {* dumps the $name variable *}

{dump}       {* descarta todas as variáveis definidas *}

Requer o pacote Tracy.

{php}

Permite que você execute qualquer código PHP. A tag deve ser ativada usando a extensão RawPhpExtension.

{spaceless}

Elimina espaços em branco desnecessários. É semelhante ao filtro sem espaçamento.

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

Saídas:

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

A etiqueta também pode ser escrita como n:atributo:

{syntax}

As etiquetas de latte não precisam ser fechadas somente em um único aparelho de amarrar. Você pode escolher outro separador, mesmo em tempo de execução. Isto é feito por {syntax…}, onde o parâmetro pode ser:

• duplo: {{...}}
• desligado: desativa completamente as etiquetas Latte

Usando a notação n:attribute, podemos desativar o Latte apenas para um bloco JavaScript:

<script n:syntax="off">
	var obj = {var: 123}; // this isn't a tag any more
</script>

O Latte pode ser utilizado muito confortavelmente dentro do JavaScript, basta evitar construções como neste exemplo, onde a carta segue imediatamente \, veja Latte dentro do JavaScript ou CSS.

Se você desligar o Latte com o {syntax off} (ou seja, tag, não o atributo n:), ele irá ignorar estritamente todas as tags até {/syntax}.

{trace}

Lança uma exceção Latte\RuntimeException, cujo traço de pilha está no espírito dos gabaritos. Assim, ao invés de chamar funções e métodos, envolve chamar blocos e inserir gabaritos. Se você usar uma ferramenta para exibir claramente as exceções lançadas, como Tracy, você verá claramente a pilha de chamadas, incluindo todos os argumentos passados.

Ajudantes de Tag HTML

n:classe

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

Exemplo: Eu preciso do elemento ativo para ter a classe active:

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

E preciso ainda 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}

Surpreendentemente simples, não é?

n:attr

O atributo n:attr pode gerar atributos HTML arbitrários com a mesma elegância que o n:class.

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

Dependendo dos valores retornados, ele exibe, por exemplo

<input type="checkbox">

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

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

n:tag

O atributo n:tag pode mudar dinamicamente o nome de um elemento HTML.

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

Se $heading === null, o <h1> é impresso sem alterações. Caso contrário, o nome do elemento é mudado para o valor da variável, portanto para $heading === 'h3' ele escreve:

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

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

n:secontente

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

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

Dependendo dos valores da variável $error, isto será impresso:

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

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

Tradução

Para que as etiquetas de tradução funcionem, é necessário criar um tradutor. Você também pode usar o translate filtro para tradução.

{_...}

Traduz valores em outros idiomas.

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

Outros parâmetros também podem ser passados para o tradutor:

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

{translate}

Překládá části části

<h1>{translate}Order{/translate}</h1>

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

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

<h1 n:translate>Order</h1>