Skip to content

Commit

Permalink
latte improved
Browse files Browse the repository at this point in the history
  • Loading branch information
dg committed Sep 10, 2024
1 parent 9f55c69 commit 2b23586
Show file tree
Hide file tree
Showing 17 changed files with 827 additions and 695 deletions.
2 changes: 1 addition & 1 deletion best-practices/cs/lets-create-contact-form.texy
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
32 changes: 26 additions & 6 deletions latte/cs/cookbook/how-to-write-sql-queries-in-latte.texy
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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(/* ... */);
Expand All @@ -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}}
28 changes: 20 additions & 8 deletions latte/cs/cookbook/migration-from-php.texy
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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}}
40 changes: 27 additions & 13 deletions latte/cs/cookbook/migration-from-twig.texy
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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'}
Expand All @@ -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}}
28 changes: 15 additions & 13 deletions latte/cs/cookbook/passing-variables.texy
Original file line number Diff line number Diff line change
@@ -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]);
Expand Down Expand Up @@ -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}
Expand All @@ -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é'}
Expand All @@ -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}
Expand All @@ -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}
Expand All @@ -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}
Expand All @@ -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'}
Expand Down Expand Up @@ -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'}
Expand All @@ -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}}
Loading

0 comments on commit 2b23586

Please sign in to comment.