Pasar variables entre plantillas

Esta guía explica cómo se pasan las variables entre plantillas en Latte mediante distintas etiquetas, como {include}, {import}, {embed}, {layout}, {sandbox} y otras. También aprenderá a trabajar con variables dentro de las etiquetas {block} y {define}, y para qué sirve la etiqueta {parameters}.

Tipos de variables

Las variables en Latte se pueden dividir en tres categorías según cómo y dónde se definen:

Variables de entrada son las que se pasan a la plantilla desde fuera, por ejemplo desde un script PHP o mediante una etiqueta como {include}.

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

Variables del entorno son las variables existentes en el punto donde está una etiqueta concreta. Incluyen todas las variables de entrada y otras variables creadas con etiquetas como {var}, {default} o dentro de un bucle {foreach}.

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

Variables explícitas son las que se indican directamente dentro de una etiqueta y se envían a la plantilla de destino.

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

{block}

La etiqueta {block} sirve para definir bloques de código reutilizables que se pueden personalizar o extender en plantillas heredadas. Las variables del entorno definidas antes del bloque están disponibles dentro de él, pero cualquier cambio en las variables se refleja solo dentro de ese bloque.

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

{$foo}    // outputs: original

{define}

La etiqueta {define} sirve para crear bloques que se renderizan solo cuando se llaman con {include}. Las variables disponibles dentro de esos bloques dependen de si en la definición se declaran parámetros. Un bloque con parámetros declarados tiene acceso tanto a esos parámetros como a todas las variables de entrada de la plantilla donde está definido. Un bloque sin parámetros tiene acceso también a esas variables de entrada. En ninguno de los dos casos están disponibles las variables del entorno.

{define hello}
	{* has access to all input variables of the template *}
{/define}

{define hello $name}
	{* has access to the $name parameter and input variables *}
{/define}

{parameters}

La etiqueta {parameters} sirve para declarar explícitamente al principio de la plantilla las variables de entrada esperadas. Así puede documentar con facilidad las variables esperadas y sus tipos de datos. También es posible definir valores predeterminados.

{parameters int $age, string $name = 'unknown'}
<p>Age: {$age}, Name: {$name}</p>

{include file}

La etiqueta {include file} sirve para insertar una plantilla completa. A esa plantilla se le pasan tanto las variables de entrada de la plantilla donde se usa la etiqueta como las variables definidas explícitamente. Ahora bien, la plantilla de destino puede limitar el ámbito con {parameters}.

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

{include block}

Al insertar un bloque definido en la misma plantilla, se le pasan todas las variables del entorno y las definidas explícitamente:

{define blockName}
	<p>Name: {$name}, Age: {$age}</p>
{/define}

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

En este ejemplo, al bloque blockName se le pasan las variables $name y $age. El mismo comportamiento vale para {include parent}.

Al insertar un bloque de otra plantilla, solo se pasan las variables de entrada y las definidas explícitamente. Las variables del entorno no están disponibles automáticamente.

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

{layout} o {extends}

Estas etiquetas definen un layout al que se pasan las variables de entrada de la plantilla hija y las variables creadas en el código antes de los bloques:

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

Plantilla layout.latte:

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

{embed}

La etiqueta {embed} se parece a {include}, pero permite incrustar bloques en la plantilla. A diferencia de {include}, solo se pasan las variables declaradas explícitamente:

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

En este ejemplo, la plantilla menu.latte solo tiene acceso a la variable $items.

En cambio, los bloques dentro de {embed} tienen acceso a todas las variables del entorno:

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

{import}

La etiqueta {import} sirve para cargar bloques de otras plantillas. A los bloques importados se les pasan tanto las variables de entrada como las declaradas explícitamente.

{import 'buttons.latte'}

{sandbox}

La etiqueta {sandbox} aísla la plantilla para procesarla de forma segura. Las variables se pasan exclusivamente de forma explícita.

{sandbox 'secure.latte', data: $secureData}
versión: 3.x