latte improved WIP

Author: dg

best-practices/cs/lets-create-contact-form.texy

@@ -131,7 +131,7 @@ Zatím se odesílá prostý textový email obsahující pouze zprávu odeslanou
 </html>
 ```
 
-Zbývá upravit `ContactFacade`, aby tuto šablonu používal. V konstruktoru si vyžádáme třídu `LatteFactory`, která umí vyrobit objekt `Latte\Engine`, tedy [vykreslovač Latte šablon |latte:develop#jak-vykreslit-sablonu]. Pomocí metody `renderToString()` šablonu vykreslíme do souboru, prvním parametrem je cesta k šabloně a druhým jsou proměnné.
+Zbývá upravit `ContactFacade`, aby tuto šablonu používal. V konstruktoru si vyžádáme třídu `LatteFactory`, která umí vyrobit objekt `Latte\Engine`, tedy [vykreslovač Latte šablon |latte:develop#vykresleni-sablony]. Pomocí metody `renderToString()` šablonu vykreslíme do souboru, prvním parametrem je cesta k šabloně a druhým jsou proměnné.
 
 ```php
 namespace App\Model;

latte/cs/cookbook/how-to-write-sql-queries-in-latte.texy

@@ -2,9 +2,9 @@ Jak psát SQL queries v Latte?
 *****************************
 
 .[perex]
-Latte se může hodit i pro generování opravdu složitých SQL dotazů.
+Latte může být užitečným nástrojem i pro generování komplexních SQL dotazů, což zvyšuje jejich čitelnost a udržovatelnost.
 
-Pokud vytvoření SQL dotazu obsahuje řadu podmínek a proměnných, může být opravdu přehlednější ho napsat v Latte. Velmi jednoduchý příklad:
+Když SQL dotaz obsahuje mnoho podmínek a proměnných, může být jeho zápis v Latte přehlednější a flexibilnější. Zde je jednoduchý příklad demonstrující tuto výhodu:
 
 ```latte
 SELECT users.* FROM users
@@ -14,8 +14,13 @@ SELECT users.* FROM users
 WHERE groups.name = 'Admins' {ifset $country} AND country.name = {$country} {/ifset}
 ```
 
-Pomocí `$latte->setContentType()` řekneme Latte, aby k obsahu přistupovalo jako k prostému textu (nikoliv jako k HTML) a dále
-připravíme escapovací funkci, která bude řetězce escapovat přímo databázovým driverem:
+Pro správné fungování je třeba provést několik kroků:
+
+1. Nastavení typu obsahu: pomocí `$latte->setContentType()` informujeme Latte, že obsah má být zpracován jako prostý text, nikoliv jako HTML.
+
+2. Definice escapovací funkce: vytvoříme vlastní escapovací funkci, která bude řetězce escapovat přímo pomocí databázového driveru. Tím zajistíme bezpečnost proti SQL injection.
+
+Zde je ukázka implementace těchto kroků:
 
 ```php
 $db = new PDO(/* ... */);
@@ -31,13 +36,28 @@ $latte->addFilter('escape', fn($val) => match (true) {
 });
 ```
 
-Použití by vypadalo takto:
+Tato escapovací funkce zajišťuje správné ošetření různých datových typů:
+- Řetězce jsou escapovány pomocí metody `quote()` databázového driveru.
+- Čísla (celá i s plovoucí desetinnou čárkou) jsou převedena na řetězce.
+- Booleovské hodnoty jsou převedeny na '1' nebo '0'.
+- Null hodnoty jsou převedeny na 'NULL'.
+- Pro nepodporované typy je vyhozena výjimka.
+
+Použití v praxi by pak vypadalo takto:
 
 ```php
 $sql = $latte->renderToString('query.sql.latte', ['country' => $country]);
 $result = $db->query($sql);
 ```
 
-*Uvedený příklad vyžaduje Latte v3.0.5 nebo vyšší.*
+Tento přístup umožňuje:
+1. Dynamické sestavování SQL dotazů s využitím logiky Latte.
+2. Bezpečné vkládání proměnných do dotazu díky vlastní escapovací funkci.
+3. Lepší čitelnost a udržovatelnost komplexních SQL dotazů.
+
+.[note]
+Tento příklad vyžaduje Latte ve verzi 3.0.5 nebo novější.
+
+Využití Latte pro generování SQL dotazů může výrazně zjednodušit práci s komplexními dotazy, zejména v situacích, kdy se dotaz dynamicky mění na základě různých podmínek. Zároveň tento přístup pomáhá udržet kód čistý a snadno upravitelný.
 
 {{leftbar: /@left-menu}}

latte/cs/cookbook/migration-from-php.texy

@@ -2,27 +2,30 @@ Migrace z PHP do Latte
 **********************
 
 .[perex]
-Převádíte starý projekt napsaný v čistém PHP do Latte? Máme pro vás nástroj, které vám migraci usnadní. [Vyzkoušejte jej online |https://php2latte.nette.org].
+Převádíte starší projekt napsaný v čistém PHP na Latte? Máme pro vás nástroj, který tento proces výrazně zjednoduší. [Vyzkoušejte jej online |https://php2latte.nette.org].
 
-Nástroj si můžete stáhnout z [GitHubu|https://github.com/nette/latte-tools] nebo nainstalovat pomocí Composeru:
+Tento užitečný nástroj můžete získat dvěma způsoby:
+
+1. Stáhnout z [GitHubu|https://github.com/nette/latte-tools]
+2. Nainstalovat pomocí Composeru:
 
 ```shell
 composer create-project latte/tools
 ```
 
-Převodník nepoužívá jednoduché záměny pomocí regulárních výrazů, naopak využívá přímo PHP parser, takže si poradí s jakkoliv složitou syntaxí.
+Na rozdíl od jednoduchých nástrojů využívajících regulární výrazy, tento převodník používá sofistikovaný PHP parser. Díky tomu si poradí i s komplexní PHP syntaxí.
 
-K převodu z PHP do Latte slouží skript `php-to-latte.php`:
+Pro převod z PHP do Latte použijte skript `php-to-latte.php`:
 
 ```shell
 php-to-latte.php input.php [output.latte]
 ```
 
 
-Příklad
--------
+Příklad použití
+---------------
 
-Vstupní soubor může vypadat třeba takto (jde o část kódu fóra PunBB):
+Podívejme se na konkrétní příklad. Níže je ukázka vstupního PHP souboru (část kódu fóra PunBB):
 
 ```php
 <h1><span><?= $lang_common['User list'] ?></span></h1>
@@ -48,7 +51,7 @@ foreach ($result as $cur_group) {
 </div>
 ```
 
-Vygeneruje tuto šablonu:
+Po zpracování nástrojem získáme následující Latte šablonu:
 
 ```latte
 <h1><span>{$lang_common['User list']}</span></h1>
@@ -69,4 +72,13 @@ Vygeneruje tuto šablonu:
 </div>
 ```
 
+Hlavní výhody tohoto převodu:
+
+1. **Čistší syntaxe**: Latte šablona je čitelnější a snáze udržovatelná.
+2. **Automatické escapování**: Latte automaticky escapuje výstup, čímž zvyšuje bezpečnost (např. `htmlspecialchars()` již není potřeba).
+3. **Lepší struktura**: Latte tagy (`{foreach}`, `{if}`) jasně oddělují logiku od prezentace.
+4. **Zjednodušení**: Odstraňuje nutnost explicitního výpisu pomocí `echo`.
+
+Tento nástroj významně urychluje a zjednodušuje proces migrace z PHP na Latte, což vám umožní rychleji modernizovat vaše projekty a využít všech výhod, které Latte nabízí.
+
 {{leftbar: /@left-menu}}

latte/cs/cookbook/migration-from-twig.texy

@@ -2,37 +2,40 @@ Migrace z Twigu do Latte
 ************************
 
 .[perex]
-Převádíte projekt napsaný v Twigu do modernějšího Latte? Máme pro vás nástroj, které vám migraci usnadní. [Vyzkoušejte jej online |https://twig2latte.nette.org].
+Převádíte projekt z Twigu na modernější a mnohem bezpečnější Latte? Máme pro vás nástroj, který tento proces výrazně zjednoduší. [Vyzkoušejte jej online |https://twig2latte.nette.org].
 
-Nástroj si můžete stáhnout z [GitHubu|https://github.com/nette/latte-tools] nebo nainstalovat pomocí Composeru:
+Tento užitečný nástroj je dostupný dvěma způsoby:
+
+1. Stažením z [GitHubu|https://github.com/nette/latte-tools]
+2. Instalací pomocí Composeru:
 
 ```shell
 composer create-project latte/tools
 ```
 
-Převodník nepoužívá jednoduché záměny pomocí regulárních výrazů, naopak využívá přímo Twig parser, takže si poradí s jakkoliv složitou syntaxí.
+Na rozdíl od jednoduchých nástrojů využívajících regulární výrazy, tento převodník používá sofistikovaný Twig parser. Díky tomu si poradí i s komplexní Twig syntaxí.
 
-K převodu z Twigu do Latte slouží skript `twig-to-latte.php`:
+Pro převod z Twigu do Latte použijte skript `twig-to-latte.php`:
 
 ```shell
 twig-to-latte.php input.twig.html [output.latte]
 ```
 
 
-Konverze
---------
+Konverze a její specifika
+-------------------------
 
-Převod předpokládá ruční úpravu výsledku, protože konverzi nelze provést jednoznačně. Twig používá tečkovou syntax, kde `{{ a.b }}` může znamenat `$a->b`, `$a['b']` nebo  `$a->getB()`, což nelze rozlišit při kompilaci. Převaděč proto vše převádí na `$a->b`.
+Je důležité poznamenat, že převod může vyžadovat ruční úpravy výsledku. Důvodem je, že některé konstrukce v Twigu nelze jednoznačně převést do Latte. Například, Twig používá tečkovou syntax, kde `{{ a.b }}` může znamenat `$a->b`, `$a['b']` nebo `$a->getB()`. Tento rozdíl nelze rozlišit při kompilaci, proto převaděč vše převádí na `$a->b`.
 
-Některé funkce, filtry nebo tagy nemají obdobu v Latte, nebo se mohou chovat mírně jinak.
+Některé funkce, filtry nebo tagy v Twigu nemají přímou obdobu v Latte, nebo se mohou chovat mírně odlišně. To je další důvod, proč může být potřeba ruční úprava po automatickém převodu.
 
 
-Příklad
--------
+Příklad použití
+---------------
 
-Vstupní soubor může vypadat třeba takto:
+Podívejme se na konkrétní příklad. Níže je ukázka vstupního Twig souboru:
 
-```latte
+```twig
 {% use "blocks.twig" %}
 <!DOCTYPE html>
 <html>
@@ -54,7 +57,7 @@ Vstupní soubor může vypadat třeba takto:
 </html>
 ```
 
-Po konverzi do Latte získáme tuto šablonu:
+Po konverzi do Latte získáme následující šablonu:
 
 ```latte
 {import 'blocks.latte'}
@@ -78,4 +81,15 @@ Po konverzi do Latte získáme tuto šablonu:
 </html>
 ```
 
+Hlavní rozdíly a výhody po převodu:
+
+1. **Změna syntaxe**: Twig používá `{% ... %}` pro logiku a `{{ ... }}` pro výpis, zatímco Latte používá jednotnou `{ ... }` syntaxi
+2. **Bloky**: `{% block ... %}` se mění na `{block ...}`
+3. **Cykly**: `{% for ... %}` se převádí na `{foreach ...}`
+4. **Podmínky**: `{% if ... %}` zůstává podobné, ale používá se `{if ...}`.
+5. **Přístup k proměnným**: Tečková notace `item.caption` se mění na objektovou notaci `$item->caption`
+6. **Import**: `{% use ... %}` se mění na `{import ...}`
+
+Tento nástroj významně urychluje a zjednodušuje proces migrace z Twigu na Latte. Umožňuje vám rychle modernizovat vaše projekty a využít všech výhod, které Latte nabízí, včetně jeho výkonu a flexibilnity. Nezapomeňte však po automatickém převodu zkontrolovat a případně upravit výsledný kód, aby plně odpovídal vašim potřebám a specifikům vašeho projektu.
+
 {{leftbar: /@left-menu}}

latte/cs/cookbook/passing-variables.texy

@@ -1,14 +1,14 @@
 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}`.
+Tento průvodce objasňuje, jak se v Latte předávají proměnné mezi šablonami 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:
+V Latte rozlišujeme tři kategorie proměnných podle jejich definice a dostupnosti:
 
-**Vstupní proměnné** jsou ty, které jsou do šablony předávány zvenčí, například z PHP skriptu nebo pomocí tagu jako `{include}`.
+**Vstupní proměnné** jsou předávány do šablony zvenčí, typicky z PHP skriptu nebo pomocí tagů jako `{include}`.
 
 ```php
 $latte->render('template.latte', ['userName' => 'Jan', 'userAge' => 30]);
@@ -45,7 +45,7 @@ Tag `{block}` se používá k definování opakovaně použitelných bloků kód
 
 `{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.
+Tag `{define}` vytváří bloky, které se renderují až po jejich explicitním zavolání pomocí `{include}`. Dostupnost proměnných uvnitř těchto bloků závisí na přítomnosti parametrů v definici. S parametry mají bloky přístup pouze k těmto parametrům. Bez parametrů mají přístup ke všem vstupním proměnným šablony, ve které jsou definovány.
 
 ```latte
 {define hello}
@@ -60,7 +60,7 @@ Tag `{define}` slouží k vytváření bloků, které se renderují až po jejic
 
 `{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.
+Tag `{parameters}` slouží k explicitní deklaraci očekávaných vstupních proměnných na začátku šablony. Tímto způsobem lze efektivně dokumentovat očekávané proměnné a jejich datové typy. Umožňuje také definovat výchozí hodnoty.
 
 ```latte
 {parameters int $age, string $name = 'neznámé'}
@@ -70,7 +70,7 @@ Tag `{parameters}` slouží k explicitní deklaraci očekávaných vstupních pr
 
 `{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}`.
+Tag `{include file}` vkládá celou šablonu. Do vkládané šablony se předávají vstupní proměnné šablony, ve které je značka použita, spolu s explicitně definovanými proměnnými. Cílová šablona může omezit rozsah přijímaných proměnných pomocí `{parameters}`.
 
 ```latte
 {include 'profile.latte', userId: $user->id}
@@ -79,7 +79,7 @@ Tag `{include file}` slouží k vložení celé šablony. Této šabloně se př
 
 `{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é:
+Při vkládání bloku definovaného ve stejné šabloně se do něj předávají všechny okolní a explicitně definované proměnné:
 
 ```latte
 {define blockName}
@@ -90,9 +90,9 @@ Když vkládáte blok definovaný ve stejné šabloně, předávají se do něj
 {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}`.
+V tomto příkladu jsou proměnné `$name` a `$age` předány do bloku `blockName`. Stejně 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é.
+Při vkládání bloku z jiné šablony se předávají pouze vstupní proměnné a explicitně definované proměnné. Okolní proměnné nejsou automaticky dostupné.
 
 ```latte
 {include blockInOtherTemplate, name: $name, age: $age}
@@ -101,7 +101,7 @@ Při vkládání bloku z jiné šablony jsou předávány pouze vstupní proměn
 
 `{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:
+Tyto tagy definují layout, do kterého se předávají vstupní proměnné podřízené šablony a proměnné vytvořené v kódu před bloky:
 
 ```latte
 {layout 'layout.latte'}
@@ -134,15 +134,15 @@ Naopak v blocích uvnitř `{embed}` je přístup ke všem okolním proměnným:
 {var $name = 'Jan'}
 {embed 'menu.latte', items: $menuItems}
 	{block foo}
-		{$nam}
+		{$name}
 	{/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ů.
+Tag `{import}` se používá pro načítání bloků z jiných šablon. Do importovaných bloků se předávají jak vstupní, tak explicitně deklarované proměnné.
 
 ```latte
 {import 'buttons.latte'}
@@ -151,11 +151,13 @@ Tag `{import}` se využívá pro načítání bloků z jiných šablon. Přená
 
 `{sandbox}`
 -----------
-Tag `{sandbox}` izoluje šablonu pro bezpečné zpracování. Proměnné jsou předávány výhradně explicitně.
+Tag `{sandbox}` izoluje šablonu pro bezpečné zpracování. Proměnné jsou předávány výhradně explicitně, což zvyšuje kontrolu nad daty vstupujícími do izolovaného prostředí.
 
 ```latte
 {sandbox 'secure.latte', data: $secureData}
 ```
 
+Tento mechanismus umožňuje přesnou kontrolu nad tím, jaká data jsou dostupná v izolované šabloně, což je užitečné pro zpracování potenciálně nebezpečného obsahu.
+
 
 {{leftbar: /@left-menu}}