Passagem de variáveis entre templates

Este guia explica como as variáveis são passadas entre templates em Latte usando várias tags como {include}, {import}, {embed}, {layout}, {sandbox} e outras. Você também aprenderá como trabalhar com variáveis na tag {block} e {define}, e para que serve a tag {parameters}.

Tipos de variáveis

As variáveis em Latte podem ser divididas em três categorias, dependendo de como e onde são definidas:

Variáveis de entrada são aquelas que são passadas para o template de fora, por exemplo, de um script PHP ou usando uma tag como {include}.

$latte->render('template.latte', ['userName' => 'Jan', 'userAge' => 30]);

Variáveis de ambiente são variáveis existentes no local de uma determinada tag. Incluem todas as variáveis de entrada e outras variáveis criadas usando tags como {var}, {default} ou dentro de um loop {foreach}.

{foreach $users as $user}
	{include 'userBox.latte', user: $user}
{/foreach}

Variáveis explícitas são aquelas que são especificadas diretamente dentro da tag e são enviadas para o template de destino.

{include 'userBox.latte', name: $user->name, age: $user->age}

{block}

A tag {block} é usada para definir blocos de código reutilizáveis que podem ser personalizados ou estendidos em templates herdados. As variáveis de ambiente definidas antes do bloco estão disponíveis dentro do bloco, mas quaisquer alterações nas variáveis se refletirão apenas dentro desse bloco.

{var $foo = 'original'}
{block example}
	{var $foo = 'alterado'}
{/block}

{$foo}    // imprime: original

{define}

A tag {define} serve para criar blocos que são renderizados apenas após serem chamados usando {include}. As variáveis disponíveis dentro desses blocos dependem se parâmetros são especificados na definição. Se sim, eles têm acesso apenas a esses parâmetros. Se não, eles têm acesso a todas as variáveis de entrada do template no qual os blocos são definidos.

{define hello}
	{* tem acesso a todas as variáveis de entrada do template *}
{/define}

{define hello $name}
	{* tem acesso apenas ao parâmetro $name *}
{/define}

{parameters}

A tag {parameters} serve para declarar explicitamente as variáveis de entrada esperadas no início do template. Desta forma, é fácil documentar as variáveis esperadas e seus tipos de dados. Também é possível definir valores padrão.

{parameters int $age, string $name = 'desconhecido'}
<p>Idade: {$age}, Nome: {$name}</p>

{include file}

A tag {include file} serve para inserir um template inteiro. Tanto as variáveis de entrada do template no qual a tag é usada quanto as variáveis explicitamente definidas nela são passadas para este template. O template de destino, no entanto, pode limitar o escopo usando {parameters}.

{include 'profile.latte', userId: $user->id}

{include block}

Ao incluir um bloco definido no mesmo template, todas as variáveis de ambiente e explicitamente definidas são passadas para ele:

{define blockName}
	<p>Nome: {$name}, Idade: {$age}</p>
{/define}

{var $name = 'Jan', $age = 30}
{include blockName}

Neste exemplo, as variáveis $name e $age são passadas para o bloco blockName. O {include parent} se comporta da mesma maneira.

Ao incluir um bloco de outro template, apenas as variáveis de entrada e explicitamente definidas são passadas. As variáveis de ambiente não estão automaticamente disponíveis.

{include blockInOtherTemplate, name: $name, age: $age}

{layout} ou {extends}

Estas tags definem o layout para o qual as variáveis de entrada do template filho e, adicionalmente, as variáveis criadas no código antes dos blocos são passadas:

{layout 'layout.latte'}
{var $seo = 'index, follow'}

Template layout.latte:

<head>
	<meta name="robots" content="{$seo}">
</head>

{embed}

A tag {embed} é semelhante à tag {include}, mas permite a inserção de blocos no template. Ao contrário de {include}, apenas as variáveis explicitamente declaradas são passadas:

{embed 'menu.latte', items: $menuItems}
{/embed}

Neste exemplo, o template menu.latte tem acesso apenas à variável $items.

Por outro lado, nos blocos dentro de {embed}, há acesso a todas as variáveis de ambiente:

{var $name = 'Jan'}
{embed 'menu.latte', items: $menuItems}
	{block foo}
		{$name}
	{/block}
{/embed}

{import}

A tag {import} é usada para carregar blocos de outros templates. Tanto as variáveis de entrada quanto as explicitamente declaradas são transferidas para os blocos importados.

{import 'buttons.latte'}

{sandbox}

A tag {sandbox} isola o template para processamento seguro. As variáveis são passadas exclusivamente de forma explícita.

{sandbox 'secure.latte', data: $secureData}
versão: 3.0