Passing Variables Across Templates

This guide explains how variables are passed between templates in Latte using various tags such as {include}, {import}, {embed}, {layout}, {sandbox}, and others. You will also learn how to work with variables in the {block} and {define} tags, and the purpose of the {parameters} tag.

Types of Variables

Variables in Latte can be divided into three categories based on how and where they are defined:

Input Variables are those that are passed to the template from outside, for example, from a PHP script or using a tag like {include}.

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

Surrounding Variables are variables existing at the location of a specific tag. These include all input variables and other variables created using tags like {var}, {default}, or within a loop {foreach}.

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

Explicit Variables are those directly specified within a tag and sent to the target template.

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

{block}

The {block} tag is used to define reusable code blocks that can be customized or extended in inherited templates. Surrounding variables defined before the block are available inside the block, but any changes to the variables are reflected only within that block.

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

{$foo}    // outputs: original

{define}

The {define} tag is used to create blocks that are rendered only when called using {include}. The variables available inside these blocks depend on whether parameters are specified in the definition. If parameters are specified, only those parameters are accessible. If not, all input variables of the template where the blocks are defined are accessible.

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

{define hello $name}
	{* has access only to the $name parameter *}
{/define}

{parameters}

The {parameters} tag is used to explicitly declare expected input variables at the beginning of the template. This way, you can easily document expected variables and their data types. It is also possible to define default values.

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

{include file}

The {include file} tag is used to insert an entire template. This template is passed both the input variables of the template where the tag is used and explicitly defined variables. However, the target template can limit the scope using {parameters}.

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

{include block}

When inserting a block defined in the same template, all surrounding and explicitly defined variables are passed to it:

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

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

In this example, the $name and $age variables are passed to the blockName block. The same behavior applies to {include parent}.

When inserting a block from another template, only input variables and explicitly defined variables are passed. Surrounding variables are not automatically available.

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

{layout} or {extends}

These tags define a layout to which input variables of the child template and variables created in the code before the blocks are passed:

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

Template layout.latte:

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

{embed}

The {embed} tag is similar to the {include} tag but allows embedding blocks into the template. Unlike {include}, only explicitly declared variables are passed:

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

In this example, the menu.latte template has access only to the $items variable.

Conversely, blocks inside {embed} have access to all surrounding variables:

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

{import}

The {import} tag is used to load blocks from other templates. Both input and explicitly declared variables are passed to the imported blocks.

{import 'buttons.latte'}

{sandbox}

The {sandbox} tag isolates the template for safe processing. Variables are passed exclusively explicitly.

{sandbox 'secure.latte', data: $secureData}
version: 3.0