application: improved info about template variables and extensions

Author: dg

application/cs/templates.texy

@@ -114,13 +114,32 @@ Soubory, kde se dohledávají šablony layoutu, lze změnit překrytím metody [
 Proměnné v šabloně
 ------------------
 
-Proměnné do šablony předáváme tak, že je zapíšeme do `$this->template` a potom je máme k dispozici v šabloně jako lokální proměnné:
+Proměnné do šablony předáváme zápisem do `$this->template`. V šabloně jsou pak dostupné jako lokální proměnné:
 
 ```php
 $this->template->article = $this->articles->getById($id);
 ```
 
-Takto jednoduše můžeme do šablon předat jakékoliv proměnné. Při vývoji robustních aplikací ale bývá užitečnější se omezit. Například tak, že explicitně nadefinujeme výčet proměnných, které šablona očekává, a jejich typů. Díky tomu nám bude moci PHP kontrolovat typy, IDE správně našeptávat a statická analýza odhalovat chyby.
+
+Výchozí proměnné
+----------------
+
+Presentery a komponenty předávají do šablon několik užitečných proměnných automaticky:
+
+- `$basePath` je absolutní URL cesta ke kořenovému adresáři (např. `/eshop`)
+- `$baseUrl` je absolutní URL ke kořenovému adresáři (např. `http://localhost/eshop`)
+- `$user` je objekt [reprezentující uživatele |security:authentication]
+- `$presenter` je aktuální presenter
+- `$control` je aktuální komponenta nebo presenter
+- `$flashes` pole [zpráv |presenters#Flash zprávy] zaslaných funkcí `flashMessage()`
+
+Pokud používáte vlastní třídu šablony, tyto proměnné se předají, pokud pro ně vytvoříte property.
+
+
+Typově bezpečné proměnné
+------------------------
+
+Při vývoji robustních aplikací je užitečné explicitně nadefinovat, jaké proměnné šablona očekává a jakého jsou typu. Získáte tak typovou kontrolu v PHP, chytré našeptávání v IDE a schopnost statické analýzy odhalovat chyby.
 
 A jak takový výčet nadefinujeme? Jednoduše v podobě třídy a její properties. Pojmenujeme ji podobně jako presenter, jen s `Template` na konci:
 
@@ -169,21 +188,6 @@ public function renderDefault(): void
 ```
 
 
-Výchozí proměnné
-----------------
-
-Presentery a komponenty předávají do šablon několik užitečných proměnných automaticky:
-
-- `$basePath` je absolutní URL cesta ke kořenovému adresáři (např. `/eshop`)
-- `$baseUrl` je absolutní URL ke kořenovému adresáři (např. `http://localhost/eshop`)
-- `$user` je objekt [reprezentující uživatele |security:authentication]
-- `$presenter` je aktuální presenter
-- `$control` je aktuální komponenta nebo presenter
-- `$flashes` pole [zpráv |presenters#Flash zprávy] zaslaných funkcí `flashMessage()`
-
-Pokud používáte vlastní třídu šablony, tyto proměnné se předají, pokud pro ně vytvoříte property.
-
-
 Vytváření odkazů
 ----------------
 
@@ -205,21 +209,44 @@ Více informací najdete v kapitole [Vytváření odkazů URL|creating-links].
 Vlastní filtry, značky apod.
 ----------------------------
 
-Šablonovací systém Latte lze rozšířit o vlastní filtry, funkce, značky apod. Lze tak učinit přímo v metodě `render<View>` nebo `beforeRender()`:
+Šablonovací systém Latte lze rozšířit o vlastní filtry, funkce, značky a další prvky. K dispozici jsou tři způsoby, jak to udělat, od nejrychlejších ad-hoc řešení až po architektonický přístup pro celou aplikaci.
+
+**Ad-hoc v metodách presenteru**
+
+Nejrychlejší způsob je přidat filtr nebo funkci přímo v kódu presenteru či komponenty. V presenteru je k tomu vhodná metoda `beforeRender()` nebo `render<View>()`:
 
 ```php
-public function beforeRender(): void
+protected function beforeRender(): void
 {
 	// přidání filtru
-	$this->template->addFilter('foo', /* ... */);
+	$this->template->addFilter('money', fn($val) => round($val) . ' Kč');
+
+	// přidání funkce
+	$this->template->addFunction('isWeekend', fn($date) => $date->format('N') >= 6);
+}
+```
+
+V šabloně pak:
+
+```latte
+<p>Cena: {$price|money}</p>
+
+{if isWeekend($now)} ... {/if}
+```
+
+Pro složitější logiku můžete konfigurovat přímo objekt `Latte\Engine`:
 
-	// nebo konfigurujeme přímo objekt Latte\Engine
+```php
+protected function beforeRender(): void
+{
 	$latte = $this->template->getLatte();
 	$latte->setMigrationWarnings();
 }
 ```
 
-Latte ve verzi 3 nabízí pokročilejší způsob a to vytvoření si [extension |latte:extending-latte#Latte Extension] pro každý webový projekt. Kusý příklad takové třídy:
+**Globálně pomocí Extension**
+
+Předchozí způsoby jsou vhodné pro filtry a funkce, které potřebujete jen v konkrétním presenteru nebo komponentě, nikoliv v celé aplikaci. Pro celou aplikaci je nejvhodnější vytvořit si [extension |latte:extending-latte#Latte Extension]. Jde o třídu, která centralizuje všechna rozšíření Latte pro celý projekt. Kusý příklad:
 
 ```php
 namespace App\Presentation\Accessory;
@@ -251,18 +278,25 @@ final class LatteExtension extends Latte\Extension
 		];
 	}
 
+	private function filterTimeAgoInWords(DateTimeInterface $time): string
+	{
+		// ...
+	}
+
 	// ...
 }
 ```
 
-Zaregistrujeme ji pomocí [konfigurace |configuration#Šablony Latte]:
+Extension zaregistrujeme pomocí [konfigurace |configuration#Šablony Latte]:
 
 ```neon
 latte:
 	extensions:
 		- App\Presentation\Accessory\LatteExtension
 ```
 
+Výhodou extension je, že lze využít dependency injection, mít přístup k modelové vrstvě aplikace a všechna rozšíření mít přehledně na jednom místě. Extension umožnuje definovat i vlastní značky, providery, průchody pro Latte kompilátor a další.
+
 
 Překládání
 ----------

application/en/templates.texy

@@ -111,16 +111,35 @@ Using `$this->setLayout(false)` or the `{layout none}` tag inside the template d
 The files where layout templates are looked up can be changed by overriding the [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()] method, which returns an array of possible file names.
 
 
-Variables in the Template
--------------------------
+Template Variables
+------------------
 
-Variables are passed to the template by writing them to `$this->template`, and then they are available in the template as local variables:
+Variables are passed to templates by writing them to `$this->template`. They then become available in the template as local variables:
 
 ```php
 $this->template->article = $this->articles->getById($id);
 ```
 
-This way, we can easily pass any variables to templates. However, when developing robust applications, it is often more useful to impose limitations. For example, by explicitly defining a list of variables that the template expects and their types. This allows PHP to perform type checking, the IDE to provide correct autocompletion, and static analysis to detect errors.
+
+Default Variables
+-----------------
+
+Presenters and components automatically pass several useful variables to templates:
+
+- `$basePath` is the absolute URL path to the root directory (e.g., `/eshop`)
+- `$baseUrl` is the absolute URL to the root directory (e.g., `http://localhost/eshop`)
+- `$user` is an object [representing the user |security:authentication]
+- `$presenter` is the current presenter
+- `$control` is the current component or presenter
+- `$flashes` is an array of [messages |presenters#Flash Messages] sent by the `flashMessage()` function
+
+If you use a custom template class, these variables are passed if you create a property for them.
+
+
+Type-Safe Variables
+-------------------
+
+When developing robust applications, it's useful to explicitly define which variables the template expects and their types. This provides type checking in PHP, smart hints in your IDE, and enables static analysis to catch errors.
 
 And how do we define such a list? Simply in the form of a class and its properties. We name it similarly to the presenter, but with `Template` at the end:
 
@@ -169,21 +188,6 @@ public function renderDefault(): void
 ```
 
 
-Default Variables
------------------
-
-Presenters and components automatically pass several useful variables to templates:
-
-- `$basePath` is the absolute URL path to the root directory (e.g., `/eshop`)
-- `$baseUrl` is the absolute URL to the root directory (e.g., `http://localhost/eshop`)
-- `$user` is an object [representing the user |security:authentication]
-- `$presenter` is the current presenter
-- `$control` is the current component or presenter
-- `$flashes` is an array of [messages |presenters#Flash Messages] sent by the `flashMessage()` function
-
-If you use a custom template class, these variables are passed if you create a property for them.
-
-
 Creating Links
 --------------
 
@@ -205,21 +209,44 @@ More information can be found in the chapter [Creating URL Links|creating-links]
 Custom Filters, Tags, etc.
 --------------------------
 
-The Latte templating system can be extended with custom filters, functions, tags, etc. This can be done directly in the `render<View>` or `beforeRender()` method:
+The Latte templating system can be extended with custom filters, functions, tags, and other elements. There are three approaches available, ranging from quick ad-hoc solutions to architectural patterns for entire applications.
+
+**Ad-hoc in Presenter Methods**
+
+The quickest approach is adding filters or functions directly in presenter or component code. In presenters, the `beforeRender()` or `render<View>()` methods work well for this:
 
 ```php
-public function beforeRender(): void
+protected function beforeRender(): void
 {
 	// adding a filter
-	$this->template->addFilter('foo', /* ... */);
+	$this->template->addFilter('money', fn($val) => '$' . number_format($val, 2));
+
+	// adding a function
+	$this->template->addFunction('isWeekend', fn($date) => $date->format('N') >= 6);
+}
+```
+
+In the template:
+
+```latte
+<p>Price: {$price|money}</p>
+
+{if isWeekend($now)} ... {/if}
+```
+
+For more complex logic, you can configure the `Latte\Engine` object directly:
 
-	// or configure the Latte\Engine object directly
+```php
+protected function beforeRender(): void
+{
 	$latte = $this->template->getLatte();
 	$latte->setMigrationWarnings();
 }
 ```
 
-Latte version 3 offers a more advanced way by creating an [extension |latte:extending-latte#Latte Extension] for each web project. Here is a brief example of such a class:
+**Globally Using Extensions**
+
+The previous approaches suit filters and functions needed only in specific presenters or components, not application-wide. For the entire application, creating an [extension |latte:extending-latte#Latte Extension] works best. This class centralizes all Latte extensions for your project. A brief example:
 
 ```php
 namespace App\Presentation\Accessory;
@@ -251,18 +278,25 @@ final class LatteExtension extends Latte\Extension
 		];
 	}
 
+	private function filterTimeAgoInWords(DateTimeInterface $time): string
+	{
+		// ...
+	}
+
 	// ...
 }
 ```
 
-We register it using [configuration |configuration#Latte Templates]:
+Register the extension through [configuration |configuration#Latte Templates]:
 
 ```neon
 latte:
 	extensions:
 		- App\Presentation\Accessory\LatteExtension
 ```
 
+Extensions offer several advantages: dependency injection support, access to your application's model layer, and centralized management of all extensions. They also support custom tags, providers, compiler passes, and more.
+
 
 Translating
 -----------