latte: added passing-variables

latte/cs/cookbook/@home.texy

@@ -5,6 +5,7 @@ Návody a postupy
 Příklady kódů a receptů pro provádění běžných úkolů pomocí Latte.
 
 - [Postupy pro vývojáře |/develop]
+- [Předávání proměnných napříč šablonami |passing-variables]
 - [Všechno, co jste kdy chtěli vědět o seskupování |grouping]
 - [Jak psát SQL queries v Latte? |how-to-write-sql-queries-in-latte]
 - [Migrace z Latte 2 |migration-from-latte2]

latte/cs/cookbook/passing-variables.texy

@@ -0,0 +1,161 @@
+Předávání proměnných napříč šablonami
+*************************************
+
+Tento průvodce vám vysvětlí, jak se proměnné předávají mezi šablonami v Latte pomocí různých tagů jako `{include}`, `{import}`, `{embed}`, `{layout}`, `{sandbox}` a dalších. Dozvíte se také, jak pracovat s proměnnými v tagu `{block}` a `{define}`, a k čemu slouží značka `{parameters}`.
+
+
+Typy proměnných
+---------------
+Proměnné v Latte můžeme rozdělit do tří kategorií podle toho, jak a kde jsou definovány:
+
+**Vstupní proměnné** jsou ty, které jsou do šablony předávány zvenčí, například z PHP skriptu nebo pomocí tagu jako `{include}`.
+
+```php
+$latte->render('template.latte', ['userName' => 'Jan', 'userAge' => 30]);
+```
+
+**Okolní proměnné** jsou proměnné existující v místě určité značky. Zahrnují všechny vstupní proměnné a další proměnné vytvořené pomocí tagů jako `{var}`, `{default}` nebo v rámci smyčky `{foreach}`.
+
+```latte
+{foreach $users as $user}
+ {include 'userBox.latte', user: $user}
+{/foreach}
+```
+
+**Explicitní proměnné** jsou ty, které jsou přímo specifikovány uvnitř tagu a jsou odeslány do cílové šablony.
+
+```latte
+{include 'userBox.latte', name: $user->name, age: $user->age}
+```
+
+
+`{block}`
+---------
+Tag `{block}` se používá k definování opakovaně použitelných bloků kódu, které lze v dědičných šablonách přizpůsobit nebo rozšířit. Okolní proměnné definované před blokem jsou dostupné uvnitř bloku, ale jakékoli změny proměnných se projeví jen v rámci toho bloku.
+
+```latte
+{var $foo = 'původní'}
+{block example}
+ {var $foo = 'změněný'}
+{/block}
+
+{$foo} // vypíše: původní
+```
+
+
+`{define}`
+----------
+Tag `{define}` slouží k vytváření bloků, které se renderují až po jejich zavolání pomocí `{include}`. Proměnné dostupné uvnitř těchto bloků závisí na tom, zda jsou v definici uvedeny parametry. Pokud ano, přístup mají jen k těmto parametrům. Pokud ne, přístup mají ke všem vstupním proměnným šablony, ve které jsou bloky definovány.
+
+```latte
+{define hello}
+ {* má přístup ke všem vstupním proměnným šablony *}
+{/define}
+
+{define hello $name}
+ {* má přístup jen k parametru $name *}
+{/define}
+```
+
+
+`{parameters}`
+--------------
+Tag `{parameters}` slouží k explicitní deklaraci očekávaných vstupních proměnných na začátku šablony. Tímto způsobem lze snadno dokumentovat očekávané proměnné a jejich datové typy. Také je možné definovat výchozí hodnoty.
+
+```latte
+{parameters int $age, string $name = 'neznámé'}
+<p>Věk: {$age}, Jméno: {$name}</p>
+```
+
+
+`{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}
+ <p>Jméno: {$name}, Věk: {$age}</p>
+{/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
+<head>
+ <meta name="robots" content="{$seo}">
+</head>
+```
+
+
+`{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}}

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]

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'}
+<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}`.
+
+```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}
+ <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.
+
+```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
+<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:
+
+```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}}