Věk: {$age}, Jméno: {$name}
+``` + + +`{include file}` +---------------- +Tag `{include file}` slouží k vložení celé šablony. Této šabloně se předávají jak vstupní proměnné šablony, ve které je značka použita, tak proměnné v ní explicitně definované. Cílová šablona ale může rozsah omezit pomocí `{parameters}`. + +```latte +{include 'profile.latte', userId: $user->id} +``` + + +`{include block}` +----------------- +Když vkládáte blok definovaný ve stejné šabloně, předávají se do něj všechny okolní a explicitně definované proměnné: + +```latte +{define blockName} +Jméno: {$name}, Věk: {$age}
+{/define} + +{var $name = 'Jan', $age = 30} +{include blockName} +``` + +V tomto příkladu se proměnné `$name` a `$age` předají do bloku `blockName`. Stejným způsobem se chová i `{include parent}`. + +Při vkládání bloku z jiné šablony jsou předávány pouze vstupní proměnné a explicitně definované. Okolní proměnné nejsou automaticky dostupné. + +```latte +{include blockInOtherTemplate, name: $name, age: $age} +``` + + +`{layout}` nebo `{extends}` +--------------------------- +Tyto tagy definují layout, do kterého se předávají vstupní proměnné podřízené šablony a dále proměnné vytvořené v kódu před bloky: + +```latte +{layout 'layout.latte'} +{var $seo = 'index, follow'} +``` + +Šablona `layout.latte`: + +```latte + + + +``` + + +`{embed}` +--------- +Tag `{embed}` je podobný tagu `{include}`, ale umožňuje vkládání bloků do šablony. Na rozdíl od `{include}` se předávají pouze explicitně deklarované proměnné: + +```latte +{embed 'menu.latte', items: $menuItems} +{/embed} +``` + +V tomto příkladu má šablona `menu.latte` přístup pouze k proměnné `$items`. + +Naopak v blocích uvnitř `{embed}` je přístup ke všem okolním proměnným: + +```latte +{var $name = 'Jan'} +{embed 'menu.latte', items: $menuItems} + {block foo} + {$nam} + {/block} +{/embed} +``` + + +`{import}` +---------- +Tag `{import}` se využívá pro načítání bloků z jiných šablon. Přenáší se jak vstupní, tak explicitně deklarované proměnné do importovaných bloků. + +```latte +{import 'buttons.latte'} +``` + + +`{sandbox}` +----------- +Tag `{sandbox}` izoluje šablonu pro bezpečné zpracování. Proměnné jsou předávány výhradně explicitně. + +```latte +{sandbox 'secure.latte', data: $secureData} +``` + + +{{leftbar: /@left-menu}} diff --git a/latte/en/cookbook/@home.texy b/latte/en/cookbook/@home.texy index 5865d71a11..d5407294bc 100644 --- a/latte/en/cookbook/@home.texy +++ b/latte/en/cookbook/@home.texy @@ -5,6 +5,7 @@ Cookbook Example codes and recipes for accomplishing common tasks with Latte. - [Developer guidelines |/develop] +- [Passing variables across templates |passing-variables] - [Everything you always wanted to know about grouping |grouping] - [How to write SQL queries in Latte? |how-to-write-sql-queries-in-latte] - [Migration from Latte 2 |migration-from-latte2] diff --git a/latte/en/cookbook/passing-variables.texy b/latte/en/cookbook/passing-variables.texy new file mode 100644 index 0000000000..2db8289f61 --- /dev/null +++ b/latte/en/cookbook/passing-variables.texy @@ -0,0 +1,161 @@ +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}`. + +```php +$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}`. + +```latte +{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. + +```latte +{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. + +```latte +{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. + +```latte +{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. + +```latte +{parameters int $age, string $name = 'unknown'} +Age: {$age}, Name: {$name}
+``` + + +`{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}`. + +```latte +{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: + +```latte +{define blockName} +Name: {$name}, Age: {$age}
+{/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. + +```latte +{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: + +```latte +{layout 'layout.latte'} +{var $seo = 'index, follow'} +``` + +Template `layout.latte`: + +```latte + + + +``` + + +`{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: + +```latte +{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: + +```latte +{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. + +```latte +{import 'buttons.latte'} +``` + + +`{sandbox}` +----------- +The `{sandbox}` tag isolates the template for safe processing. Variables are passed exclusively explicitly. + +```latte +{sandbox 'secure.latte', data: $secureData} +``` + + +{{leftbar: /@left-menu}}