passing-variables [WIP]

latte/cs/cookbook/passing-variables.texy

@@ -0,0 +1,151 @@
+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]);
+```
+
+**Kontextové proměnné** jsou proměnné existující v místě značky. Zahrnují všechny vstupní proměnné a další proměnné specificky nastavené pomocí tagů jako `{var}`, `{default}` nebo vytvořené 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 přímo 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. Proměnné definované mimo blok jsou dostupné uvnitř bloku, ale jakékoli změny proměnných v bloku 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.
+
+```latte
+{define hello}
+	{* má přístup ke všem vstupním proměnným *}
+{/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 validovat a dokumentovat očekávané proměnné.
+
+```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é, tak proměnné explicitně definované v tagu, pokud nemá omezení v `{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 kontextové a explicitně definované proměnné:
+
+```latte
+{define blockName}
+    <p>Jméno: {$name}, Věk: {$age}</p>
+{/define}
+
+{var $name = 'Jan'}
+{var $age = 30}
+{include blockName}
+```
+
+V tomto příkladu se proměnné `$name` a `$age` předají do bloku `blockName`.
+
+Totéž platí při použití `{include parent}`.
+
+Při vkládání bloku z jiné šablony jsou předávány pouze vstupní a explicitně definované proměnné. Kontextové proměnné z původní šablony nejsou automaticky dostupné.
+
+```latte
+{include blockInOtherTemplate, name: $name, age: $age}
+```
+
+V tomto příkladu se do bloku předají vstupní proměnné a dále proměnné `$name` a `$age`.
+
+
+`{layout}` nebo `{extends}`
+---------------------------
+Tyto tagy definují layout, do kterého se předávají vstupní a kontextově definované proměnné z podřízené šablony. Kód mimo bloky v podřízené šabloně se vykonává před vykreslením šablony layoutu, což umožňuje definovat proměnné a šířit data do celého řetězce dědičnosti.
+
+```latte
+{layout 'layout.latte'}
+{var $seo = 'index, follow'}
+```
+
+
+`{embed}`
+---------
+Tag `{embed}` je podobný tagu `{include}`, ale umožňuje vkládání bloků kódu do šablony. Pouze explicitně deklarované proměnné jsou předány.
+
+```latte
+{embed 'menu.latte', items: $menuItems}
+{/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'}
+{include block 'saveButton'}
+```
+
+
+`{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}
+```
+
+
+Shrnutí
+-------
+Správné používání proměnných a tagů v Latte může výrazně zlepšit strukturu a udržitelnost vašeho kódu. Nebojte se experimentovat a objevovat nové možnosti, které vám Latte nabízí. Pro hlubší pochopení doporučujeme pročíst oficiální dokumentaci Latte a zkusit si vytvořit několik vlastních šablon.
+
+
+{{leftbar: /@left-menu}}