passing-variables [WIP]

latte/cs/cookbook/passing-variables.texy

@@ -0,0 +1,132 @@
+Předávání proměnných napříč šablonami
+*************************************
+
+Tento průvodce je určen všem, kteří chtějí porozumět způsobu předávání proměnných v šablonovacím systému Latte. Zjistíte, jak proměnné fungují s různými tagy, jako jsou `{include}`, `{import}`, `{embed}`, `{layout}` a `{sandbox}`. Podrobně se zaměříme na tagy `{block}` a `{define}` a vysvětlíme využití `{parameters}` pro efektivnější správu a kontrolu vašich šablon.
+
+
+Typy proměnných
+---------------
+Proměnné v Latte můžeme rozdělit do tří základních kategorií, které se liší podle způsobu a místa definice:
+
+**Globální proměnné:** Toto jsou proměnné, které jsou předávány do šablony zvenčí, buď přímo z PHP skriptu, nebo jako součást jiných tagů, jako je `{include}`:
+
+```php
+$latte->render('template.latte', ['userName' => 'Jan', 'userAge' => 30]);
+```
+
+**Lokální proměnné:** Jde o proměnné dostupné v místě značky. Jsou to všechny globální proměnné a další proměnné specificky nastavené pomocí tagů jako `{var}`, `{default}` či vytvořené v rámci smyčky `{foreach}`:
+
+```latte
+{foreach $users as $user}
+    {include 'userBox', user: $user}
+{/foreach}
+```
+
+**Explicitní proměnné:** Jsou to proměnné, které jsou přímo specifikovány uvnitř tagu a jsou odeslány přímo do cílové šablony:
+
+```latte
+{include 'userBox', name: $user->name, age: $user->age}
+```
+
+
+`{block}`
+---------
+Tag `{block}` je ideální pro definování opakovaně použitelných bloků kódu, které lze v dědičných šablonách přizpůsobit nebo rozšířit. Bloky přistupují k proměnným definovaným vně bloku, avšak jakékoli změny proměnných v bloku zůstávají omezeny na jeho rámec:
+
+```latte
+{var $foo = 'original'}
+{block example}
+    {var $foo = 'modified'}
+{/block}
+
+{$foo}    // vypíše: original
+```
+
+
+`{define}`
+----------
+Tag `{define}` slouží k vytváření bloků, které se renderují až po jejich zavolání pomocí `{include}`. Tyto bloky nezískávají automaticky přístup k proměnným mimo svůj kontext.
+K jakým proměnným mají přístup, záleží na tom, jestli součástí definice jsou parametry. Pokud ano, předají se jí jen uvedené parametry. Pokud ne, předají se jí všechny globální parametry:
+
+```latte
+{define hello}
+	{* má přístup ke globálním parametrů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, což usnadňuje validaci a dokumentaci očekávaných dat. Je to užitečné pro správu komplexních projektů:
+
+```latte
+{parameters int $age, string $name = 'unknown'}
+<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 globální proměnné, tak proměnné explicitně definované v tagu, pokud nemá omezení v `{parameters}`:
+
+```latte
+{include 'profile.latte', userId: $user->id}
+```
+
+
+`{include block}`
+-----------------
+Při použití `{include block}` se do vkládaného bloku předávají globální a explicitně definované proměnné. Pokud je blok definován ve stejné šabloně, předávají se i lokální proměnné:
+
+```latte
+{include 'header.latte', title: 'Můj Web'}
+```
+
+
+`{layout}` nebo `{extends}`
+---------------------------
+Tyto tagy definují layout. Jsou do něj předávány jak globální, tak Jak globální, tak lokálně definované proměnné v podřízené šablonách.
+Prostor mimo bloky v podřízené šabloně se provádí před vykreslením šablony layoutu, takže je můžete použít k definování proměnných jako `{var $foo = bar}` a k šíření dat do celého řetězce dědičnosti:
+
+```latte
+{layout 'layout.latte'}
+{var $seo = 'index, follow'}
+```
+
+
+`{embed}`
+---------
+`{embed}` je podobný `{include}`, ale navíc 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}`
+----------
+`{import}` se využívá pro načítání bloků z jiných šablon. Přenáší se jak globální, 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.