Passagem de variáveis entre modelos
Este guia explica como as variáveis são passadas entre modelos no Latte usando várias tags, como {include},
{import}, {embed}, {layout}, {sandbox}, entre outras. Você também aprenderá
a trabalhar com variáveis nas tags {block} e {define} e a finalidade da tag
{parameters}.
Tipos de variáveis
As variáveis no Latte podem ser divididas em três categorias com base em como e onde são definidas:
Variáveis de entrada são aquelas que são passadas para o modelo de fora, por exemplo, de um script PHP ou usando uma
tag como {include}.
$latte->render('template.latte', ['userName' => 'Jan', 'userAge' => 30]);
Variáveis circundantes são variáveis existentes no local de uma tag específica. Elas 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 especificadas diretamente em uma tag e enviadas ao modelo 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 modelos herdados. As variáveis circundantes definidas antes do bloco estão disponíveis dentro do bloco, mas quaisquer
alterações nas variáveis são refletidas somente dentro desse bloco.
{var $foo = 'original'}
{block example}
{var $foo = 'modified'}
{/block}
{$foo} // outputs: original
{define}
A tag {define} é usada para criar blocos que são renderizados somente quando chamados usando
{include}. As variáveis disponíveis nesses blocos dependem do fato de os parâmetros terem sido especificados na
definição. Se os parâmetros forem especificados, somente esses parâmetros estarão acessíveis. Caso contrário, todas as
variáveis de entrada do modelo em que os blocos estão definidos estarão acessíveis.
{define hello}
{* has access to all input variables of the template *}
{/define}
{define hello $name}
{* has access only to the $name parameter *}
{/define}
{parameters}
A tag {parameters} é usada para declarar explicitamente as variáveis de entrada esperadas no início do modelo.
Dessa forma, você pode documentar facilmente as variáveis esperadas e seus tipos de dados. Também é possível definir valores
padrão.
{parameters int $age, string $name = 'unknown'}
<p>Age: {$age}, Name: {$name}</p>
{include file}
A tag {include file} é usada para inserir um modelo inteiro. Esse modelo recebe tanto as variáveis de entrada
do modelo em que a tag é usada quanto as variáveis definidas explicitamente. No entanto, o modelo de destino pode limitar
o escopo usando {parameters}.
{include 'profile.latte', userId: $user->id}
{include block}
Ao inserir um bloco definido no mesmo modelo, todas as variáveis circundantes e explicitamente definidas são passadas para ele:
{define blockName}
<p>Name: {$name}, Age: {$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 mesmo comportamento se aplica a {include parent}.
Ao inserir um bloco de outro modelo, somente as variáveis de entrada e as variáveis explicitamente definidas são transmitidas. As variáveis ao redor não estão automaticamente disponíveis.
{include blockInOtherTemplate, name: $name, age: $age}
{layout} ou {extends}
Essas tags definem um layout para o qual são passadas as variáveis de entrada do modelo filho e as variáveis criadas no código antes dos blocos:
{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 incorporar blocos ao modelo. Ao contrário
da {include}, somente as variáveis declaradas explicitamente são transmitidas:
{embed 'menu.latte', items: $menuItems}
{/embed}
Neste exemplo, o modelo menu.latte tem acesso apenas à variável $items.
Por outro lado, os blocos dentro de {embed} têm acesso a todas as variáveis ao redor:
{var $name = 'Jan'}
{embed 'menu.latte', items: $menuItems}
{block foo}
{$name}
{/block}
{/embed}
{import}
A tag {import} é usada para carregar blocos de outros modelos. Tanto as variáveis de entrada quanto as
explicitamente declaradas são passadas para os blocos importados.
{import 'buttons.latte'}
{sandbox}
A tag {sandbox} isola o modelo para processamento seguro. As variáveis são passadas exclusivamente de forma
explícita.
{sandbox 'secure.latte', data: $secureData}