application: improved info about template variables and extensions

dg · dg · commit 1422f06c5cca · 2025-12-01T00:45:11.000+01:00
diff --git a/application/cs/templates.texy b/application/cs/templates.texy
@@ -114,15 +114,34 @@ 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.
 
-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:
+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é šablony
+-----------------------
+
+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.
+
+Jak takový výčet nadefinovat? Jednoduše v podobě třídy s properties reprezentujícími proměnné šablony. Pojmenujeme ji podobně jako presenter, jen s `Template` na konci:
 
 ```php
 /**
@@ -141,22 +160,22 @@ class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template
 }
 ```
 
-Objekt `$this->template` v presenteru bude nyní instancí třídy `ArticleTemplate`. Takže PHP bude při zápisu kontrolovat deklarované typy. A počínaje verzí PHP 8.2 upozorní i na zápis do neexistující proměnné, v předchozích verzích lze téhož dosáhnout použitím traity [Nette\SmartObject |utils:smartobject].
+Objekt `$this->template` v presenteru bude nyní instancí třídy `ArticleTemplate`. PHP tak bude při zápisu kontrolovat deklarované typy.
 
-Anotace `@property-read` je určená pro IDE a statickou analýzu, díky ní bude fungovat našeptávání, viz "PhpStorm and code completion for $this⁠-⁠>⁠template":https://blog.nette.org/en/phpstorm-and-code-completion-for-this-template.
+Anotace `@property-read` slouží pro IDE a statickou analýzu, díky ní bude fungovat našeptávání, viz "PhpStorm and code completion for $this⁠-⁠>⁠template":https://blog.nette.org/en/phpstorm-and-code-completion-for-this-template.
 
 [* phpstorm-completion.webp *]
 
-Luxusu našeptávání si můžete dopřát i v šablonách, stačí do PhpStorm nainstalovat plugin pro Latte a uvést na začátek šablony název třídy, více v článku "Latte: jak na typový systém":https://blog.nette.org/cs/latte-jak-na-typovy-system:
+Našeptávání můžete využít i přímo v šablonách. Stačí do PhpStorm nainstalovat plugin pro Latte a uvést na začátek šablony název třídy parametrů šablony, více v článku "Latte: jak na typový systém":https://blog.nette.org/cs/latte-jak-na-typovy-system:
 
 ```latte
 {templateType App\Presentation\Article\ArticleTemplate}
 ...
 ```
 
-Takto fungují i šablony v komponentách, stačí jen dodržet jmennou konvenci a pro komponentu např. `FifteenControl` vytvořit třídu šablony `FifteenTemplate`.
+Totéž platí i pro komponenty. Stačí dodržet jmennou konvenci a pro komponentu např. `FifteenControl` vytvořit třídu parametrů `FifteenTemplate`.
 
-Pokud potřebujete vytvořit `$template` jako instanci jiné třídy, využijte metodu `createTemplate()`:
+Pokud potřebujete použít jinou třídu parametrů, využijte metodu `createTemplate()`:
 
 ```php
 public function renderDefault(): void
@@ -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,67 @@ 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);
+}
+```
 
-	// nebo konfigurujeme přímo objekt Latte\Engine
+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`:
+
+```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:
+**Pomocí atributů**
+
+Elegantní způsob je definovat filtry a funkce jako metody přímo ve [třídě parametrů šablony|#Typově bezpečné šablony] presenteru nebo komponenty a označit je atributy:
+
+```php
+class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template
+{
+	#[Latte\Attributes\TemplateFilter]
+	public function money(float $val): string
+	{
+		return round($val) . ' Kč';
+	}
+
+	#[Latte\Attributes\TemplateFunction]
+	public function isWeekend(DateTimeInterface $date): bool
+	{
+		return $date->format('N') >= 6
+	}
+}
+```
+
+Latte automaticky rozpozná a zaregistruje metody označené těmito atributy. Název filtru nebo funkce v šabloně odpovídá názvu metody. Tyto metody nesmí být privátní.
+
+**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 +301,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í
 ----------
diff --git a/application/en/templates.texy b/application/en/templates.texy
@@ -111,18 +111,37 @@ 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.
 
-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:
+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 Templates
+-------------------
+
+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.
+
+How do you define such a list? Simply as a class with properties representing template variables. Name it similarly to the presenter, just with `Template` at the end:
 
 ```php
 /**
@@ -141,22 +160,22 @@ class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template
 }
 ```
 
-The `$this->template` object in the presenter will now be an instance of the `ArticleTemplate` class. So PHP will check the declared types upon writing. And starting from PHP 8.2, it will also warn about writing to a non-existent variable; in previous versions, the same can be achieved using the [Nette\SmartObject |utils:smartobject] trait.
+The `$this->template` object in the presenter will now be an instance of the `ArticleTemplate` class. PHP will thus check the declared types when writing.
 
-The `@property-read` annotation is intended for IDEs and static analysis; thanks to it, autocompletion will work, see "PhpStorm and code completion for $this->template":https://blog.nette.org/en/phpstorm-and-code-completion-for-this-template.
+The `@property-read` annotation is for the IDE and static analysis, enabling code completion, see "PhpStorm and code completion for $this⁠-⁠>⁠template":https://blog.nette.org/en/phpstorm-and-code-completion-for-this-template.
 
 [* phpstorm-completion.webp *]
 
-You can enjoy the luxury of autocompletion in templates too; just install the Latte plugin for PhpStorm and specify the class name at the beginning of the template, more in the article "Latte: How to Use Type System":https://blog.nette.org/en/latte-how-to-use-type-system:
+You can also use code completion directly in templates. Just install the Latte plugin for PhpStorm and specify the template parameter class name at the beginning of the template, more in the article "Latte: how to use the type system":https://blog.nette.org/en/latte-how-to-use-type-system:
 
 ```latte
 {templateType App\Presentation\Article\ArticleTemplate}
 ...
 ```
 
-This is also how templates work in components; just follow the naming convention and create a template class `FifteenTemplate` for a component like `FifteenControl`.
+The same applies to components. Just follow the naming convention and create a parameter class `FifteenTemplate` for a component like `FifteenControl`.
 
-If you need to create `$template` as an instance of another class, use the `createTemplate()` method:
+If you need to use a different parameter class, use the `createTemplate()` method:
 
 ```php
 public function renderDefault(): void
@@ -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,67 @@ 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}
+```
 
-	// or configure the Latte\Engine object directly
+For more complex logic, you can 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:
+**Using Attributes**
+
+A more elegant approach is defining filters and functions as methods directly in the presenter or component's [template parameter class|#Type-safe templates], marked with attributes:
+
+```php
+class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template
+{
+	#[Latte\Attributes\TemplateFilter]
+	public function money(float $val): string
+	{
+		return '$' . number_format($val, 2);
+	}
+
+	#[Latte\Attributes\TemplateFunction]
+	public function isWeekend(DateTimeInterface $date): bool
+	{
+		return $date->format('N') >= 6
+	}
+}
+```
+
+Latte automatically discovers and registers methods marked with these attributes. The filter or function name in templates matches the method name. These methods must not be private.
+
+**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 +301,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
 -----------
