latte 3.1

Author: dg

latte/cs/@left-menu.texy

@@ -5,6 +5,7 @@
 	- [Dědičnost šablon |Template Inheritance]
 	- [Typový systém |type-system]
 	- [Sandbox]
+	- [HTML attributy |html-attributes]
 
 - Pro designéry 🎨
 	- [Syntaxe |syntax]

latte/cs/cookbook/@home.texy

@@ -8,6 +8,7 @@ Příklady kódů a receptů pro provádění běžných úkolů pomocí Latte.
 - [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 3.0 |migration-from-latte-30]
 - [Migrace z Latte 2 |migration-from-latte2]
 - [Migrace z PHP |migration-from-php]
 - [Migrace z Twigu |migration-from-twig]

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

@@ -0,0 +1,110 @@
+Migrace z Latte 3.0
+*******************
+
+Latte 3.1 přináší několik vylepšení a změn, díky kterým je psaní šablon bezpečnější a pohodlnější. Většina změn je zpětně kompatibilní, ale některé vyžadují pozornost při přechodu.
+
+Tento průvodce shrnuje BC breaky a jak je řešit.
+
+Latte 3.1 vyžaduje **PHP 8.2** nebo novější.
+
+
+Chytré atributy a migrace
+=========================
+
+Nejvýznamnější změnou v Latte 3.1 je nové chování [chytrých atributů |/html-attributes]. To ovlivňuje, jak se vykreslují hodnoty `null` a logické hodnoty v `data-` atributech.
+
+1.  **Hodnoty `null`:** Dříve se `title={$null}` vykresloval jako `title=""`. Nyní se atribut zcela vynechá.
+2.  **`data-` atributy:** Dříve se `data-foo={=true}` / `data-foo={=false}` vykreslovaly jako `data-foo="1"` / `data-foo=""`. Nyní se vykreslují jako `data-foo="true"` / `data-foo="false"`.
+
+Abychom vám pomohli identifikovat místa, kde se výstup ve vaší aplikaci změnil, Latte poskytuje migrační nástroj.
+
+
+Migrační varování
+-----------------
+
+Můžete zapnout [migrační varování |/develop#Migrační varování], která vás během vykreslování upozorní, pokud se výstup liší od Latte 3.0.
+
+```php
+$latte = new Latte\Engine;
+$latte->setMigrationWarnings();
+```
+
+Pokud jsou povolena, sledujte logy aplikace nebo Tracy bar pro `E_USER_WARNING`. Každé varování bude ukazovat na konkrétní řádek a sloupec v šabloně.
+
+**Jak varování vyřešit:**
+
+Pokud je nové chování správné (např. chcete, aby prázdný atribut zmizel), potvrďte jej použitím filtru `|accept` pro potlačení varování:
+
+```latte
+<div class="{$var|accept}"></div>
+```
+
+Pokud chcete atribut zachovat jako prázdný (např. `title=""`) místo jeho vynechání, použijte null coalescing operátor:
+
+```latte
+<div title={$var ?? ''}></div>
+```
+
+Nebo, pokud striktně vyžadujete staré chování (např. `"1"` pro `true`), explicitně přetypujte hodnotu na string:
+
+```latte
+<div data-foo={(string) $bool}></div>
+```
+
+**Poté, co vyřešíte všechna varování:**
+
+Jakmile vyřešíte všechna varování, vypněte migrační varování a **odstraňte všechny** filtry `|accept` ze svých šablon, protože již nejsou potřeba.
+
+
+Strict Types
+============
+
+Latte 3.1 zapíná `declare(strict_types=1)` ve výchozím nastavení pro všechny kompilované šablony. To zlepšuje typovou bezpečnost, ale může způsobit typové chyby v PHP výrazech uvnitř šablon, pokud jste spoléhali na volné typování.
+
+Pokud typy nemůžete opravit okamžitě, můžete toto chování vypnout:
+
+```php
+$latte->setStrictTypes(false);
+```
+
+
+Globální konstanty
+==================
+
+Parser šablon byl vylepšen, aby lépe rozlišoval mezi jednoduchými řetězci a konstantami. V důsledku toho musí být globální konstanty nyní prefixovány zpětným lomítkem `\`.
+
+```latte
+{* Starý způsob (nyní interpretováno jako řetězec 'PHP_VERSION') *}
+{if PHP_VERSION > ...}
+
+{* Nový způsob (správně interpretováno jako konstanta) *}
+{if \PHP_VERSION > ...}
+```
+
+Tato změna předchází nejednoznačnostem a umožňuje volnější používání neuvodzovkovaných řetězců.
+
+
+Odstraněné funkce
+=================
+
+**Rezervované proměnné:** Proměnné začínající na `$__` (dvou podtržítko) a proměnná `$this` jsou nyní vyhrazeny pro vnitřní použití Latte. Nemůžete je používat v šablonách.
+
+**Undefined-safe operátor:** Operátor `??->`, což byla specifická funkce Latte vytvořená před PHP 8, byl odstraněn. Jde o historický relikt. Používejte prosím standardní PHP nullsafe operátor `?->`.
+
+**Filter Loader**
+Metoda `Engine::addFilterLoader()` byla označena jako zastaralá a odstraněna. Šlo o nekonzistentní koncept, který se jinde v Latte nevyskytoval.
+
+**Date Format**
+Statická vlastnost `Latte\Runtime\Filters::$dateFormat` byla odstraněna, aby se předešlo globálnímu stavu.
+
+
+Nové funkce
+===========
+
+Během migrace si můžete začít užívat nové funkce:
+
+- **Chytré HTML atributy:** Předávání polí do `class` a `style`, automatické vynechání `null` atributů.
+- **Nullsafe filtry:** Použijte `{$var?|filter}` pro přeskočení filtrování null hodnot.
+- **`n:elseif`:** Nyní můžete používat `n:elseif` společně s `n:if` a `n:else`.
+- **Zjednodušená syntaxe:** Pište `<div n:if={$cond}>` bez uvozovek.
+- **Toggle filtr:** Použijte `|toggle` pro ruční ovládání boolean atributů.

latte/cs/custom-filters.texy

@@ -117,30 +117,6 @@ $latte->addExtension(new App\Latte\MyLatteExtension);
 Tento přístup udrží logiku vašeho filtru zapouzdřenou a registraci jednoduchou.
 
 
-Použití načítače filtrů
------------------------
-
-Latte umožňuje registrovat načítač filtrů pomocí `addFilterLoader()`. Jde o jediné volatelné callable, které Latte požádá o jakýkoliv neznámý název filtru během kompilace. Načítač vrací PHP callable filtru nebo `null`.
-
-```php
-$latte = new Latte\Engine;
-
-// Načítač může dynamicky vytvářet/získávat callable filtry
-$latte->addFilterLoader(function (string $name): ?callable {
-	if ($name === 'myLazyFilter') {
-		// Představte si zde náročnou inicializaci...
-		$service = get_some_expensive_service();
-		return fn($value) => $service->process($value);
-	}
-	return null;
-});
-```
-
-Tato metoda byla primárně určena pro líné načítání filtrů s velmi **náročnou inicializací**. Avšak moderní praktiky vkládání závislostí (dependency injection) obvykle zvládají líné služby efektivněji.
-
-Načítače filtrů přidávají složitost a obecně se nedoporučují ve prospěch přímé registrace pomocí `addFilter()` nebo v rámci rozšíření pomocí `getFilters()`. Používejte načítače pouze pokud máte závažný, specifický důvod související s výkonnostními problémy při inicializaci filtrů, které nelze řešit jinak.
-
-
 Filtry používající třídu s atributy
 -----------------------------------
 

latte/cs/develop.texy

@@ -15,7 +15,8 @@ Podporované verze PHP (platí pro poslední setinkové verze Latte):
 
 | verze           | kompatibilní s PHP
 |-----------------|-------------------
-| Latte 3.0       | PHP 8.0 – 8.2
+| Latte 3.1       | PHP 8.2 – 8.5
+| Latte 3.0       | PHP 8.0 – 8.5
 
 
 Jak vykreslit šablonu
@@ -193,6 +194,27 @@ $latte = new Latte\Engine;
 $latte->setStrictTypes();
 ```
 
+.[note]
+Od verze Latte 3.1 jsou strict types povoleny ve výchozím nastavení. Můžete je deaktivovat pomocí `$latte->setStrictTypes(false)`.
+
+
+Migrační varování .{data-version:3.1}
+=====================================
+
+Latte 3.1 mění chování některých [HTML atributů|html-attributes]. Například hodnoty `null` nyní odstraní atribut namísto vypsání prázdného řetězce. Abyste snadno našli místa, kde tato změna ovlivňuje vaše šablony, můžete zapnout varování o migraci:
+
+```php
+$latte->setMigrationWarnings();
+```
+
+Pokud je toto zapnuto, Latte kontroluje vykreslované atributy a vyvolá uživatelské varování (`E_USER_WARNING`), pokud se výstup liší od toho, co by Latte 3.0 vygenerovalo. Když narazíte na varování, použijte jedno z těchto řešení:
+
+1. Pokud je nový výstup pro váš případ použití správný (např. preferujete, aby atribut zmizel při `null`), potlačte varování přidáním filtru `|accept`
+2. Pokud chcete, aby byl atribut vykreslen jako prázdný (např. `title=""`) namísto odstranění, když je proměnná `null`, poskytněte prázdný řetězec jako zálohu: `title={$val ?? ''}`
+3. Pokud striktně vyžadujete staré chování (např. vypsání `"1"` pro `true` namísto `"true"`), explicitně přetypujte hodnotu na řetězec: `data-foo={(string) $val}`
+
+Jakmile jsou všechna varování vyřešena, vypněte varování o migraci odstraněním `setMigrationWarnings()` a **odstraňte všechny** filtry `|accept` ze svých šablon, protože již nejsou potřeba.
+
 
 Překládání v šablonách .{toc: TranslatorExtension}
 ==================================================

latte/cs/extending-latte.texy

@@ -44,13 +44,6 @@ $latte->addFilter('truncate', $myTruncate);
 // Použití v šabloně: {$text|truncate} nebo {$text|truncate:100}
 ```
 
-Můžete také zaregistrovat **Filter Loader**, funkci, která dynamicky poskytuje volatelné objekty filtrů podle požadovaného názvu:
-
-```php
-$latte->addFilterLoader(fn(string $name) => /* vrátí volatelný objekt nebo null */);
-```
-
-
 Pro registraci funkce použitelné ve výrazech šablony použijte `addFunction()`.
 
 ```php

latte/cs/filters.texy

@@ -55,6 +55,11 @@ V šablonách můžeme používat funkce, které pomáhají upravit nebo přefor
 | `floor`      | [zaokrouhlí číslo dolů na danou přesnost |#floor]
 | `round`      | [zaokrouhlí číslo na danou přesnost |#round]
 
+.[table-latte-filters]
+|## HTML atributy
+| `accept`     | [potvrzuje nové chování chytrých atributů |#accept]
+| `toggle`     | [přepíná přítomnost HTML atributu |#toggle]
+
 .[table-latte-filters]
 |## Escapování
 | `escapeUrl`  | [escapuje parametr v URL |#escapeUrl]
@@ -117,10 +122,31 @@ V šabloně se potom volá takto:
 ```
 
 
+Nullsafe filtry .{data-version:3.1}
+-----------------------------------
+
+Jakýkoliv filtr lze učinit nullsafe použitím `?|` místo `|`. Pokud je hodnota `null`, filtr se nevykoná a vrátí se `null`. Filtry následující v řetězci jsou také přeskočeny.
+
+To je užitečné v kombinaci s HTML atributy, které jsou vynechány, pokud je hodnota `null`.
+
+```latte
+<div title={$title?|upper}>
+{* Pokud je $title null: <div> *}
+{* Pokud je $title 'hello': <div title="HELLO"> *}
+```
+
+
 Filtry
 ======
 
 
+accept .[filter]{data-version:3.1}
+----------------------------------
+Filtr se používá při [migraci z Latte 3.0|cookbook/migration-from-latte-30] k potvrzení, že jste zkontrolovali změnu chování atributu a akceptujete ji. Nemění hodnotu.
+
+Jde o dočasný nástroj. Jakmile je migrace dokončena a varování při migraci jsou vypnuta, měli byste tento filtr ze svých šablon odstranit.
+
+
 batch(int $length, mixed $item): array .[filter]
 ------------------------------------------------
 Filtr, který zjednodušuje výpis lineárních dat do podoby tabulky. Vrací pole polí se zadaným počtem položek. Pokud zadáte druhý parametr, použije se k doplnění chybějících položek na posledním řádku.
@@ -827,6 +853,21 @@ Extrahuje část řetězce. Tento filtr byl nahrazen filtrem [#slice].
 ```
 
 
+toggle .[filter]{data-version:3.1}
+----------------------------------
+Filtr `toggle` ovládá přítomnost atributu na základě boolean hodnoty. Pokud je hodnota truthy, atribut je přítomen; pokud je falsy, atribut je zcela vynechán:
+
+```latte
+<div uk-grid={$isGrid|toggle}>
+{* Pokud je $isGrid truthy: <div uk-grid> *}
+{* Pokud je $isGrid falsy: <div> *}
+```
+
+Tento filtr je užitečný pro vlastní atributy nebo atributy JavaScriptových knihoven, které vyžadují kontrolu přítomnosti/nepřítomnosti podobně jako HTML boolean atributy.
+
+Filtr lze použít pouze uvnitř HTML atributů.
+
+
 translate(...$args) .[filter]
 -----------------------------
 Překládá výrazy do jiných jazyků. Aby byl filtr k dispozici, je potřeba [nastavit překladač |develop#TranslatorExtension]. Můžete také použít [tagy pro překlad |tags#Překlady].