nette/application 3.2.9

Author: dg

application/cs/presenters.texy

@@ -493,6 +493,17 @@ class MyPresenter extends Nette\Application\UI\Presenter
 Je důležité zdůraznit, že pokud povolíte metodu `OPTIONS`, musíte ji následně také patřičně obsloužit v rámci svého presenteru. Metoda je často používána jako tzv. preflight request, který prohlížeč automaticky odesílá před skutečným požadavkem, když je potřeba zjistit, zda je požadavek povolený z hlediska CORS (Cross-Origin Resource Sharing) politiky. Pokud metodu povolíte, ale neimplementujete správnou odpověď, může to vést k nekonzistencím a potenciálním bezpečnostním problémům.
 
 
+Označení zastaralých akcí .{data-version:3.2.3}
+-----------------------------------------------
+
+Atribut `#[Deprecated]` slouží k označení akcí, signálů nebo celých presenterů, které jsou zastaralé a měly by být v budoucnu odstraněny. Při generování odkazů na takto označené části aplikace Nette vyhodí varování, které vývojáře upozorní.
+
+Atribut lze aplikovat jak na celou třídu presenteru, tak na jednotlivé metody `action<Action>()`, `render<View>()` a `handle<Signal>()`.
+
+.[note]
+PHP zavedlo atribut `#[Deprecated]` sice až ve verzi 8.4, ale Nette jej podporuje i ve starších verzích.
+
+
 Další četba
 ===========
 

application/cs/templates.texy

@@ -114,13 +114,43 @@ 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.
+Pokud chcete, aby se hodnota určité property automaticky předala do šablony jako proměnná, označte ji atributem `#[TemplateVariable]`: .{data-version:3.2.9}
+
+```php
+use Nette\Application\Attributes\TemplateVariable;
+
+class ArticlePresenter extends Nette\Application\UI\Presenter
+{
+	#[TemplateVariable]
+	public string $siteName = 'Můj blog'; // nesmí být private
+}
+```
+
+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 +199,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 +220,70 @@ 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>
 
-	// nebo konfigurujeme přímo objekt Latte\Engine
+{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ů**  .{data-version:3.2.9}
+
+Elegantní způsob je definovat filtry a funkce jako metody přímo v presenteru nebo komponentě a označit je atributy:
+
+```php
+use Latte\Attributes\TemplateFilter;
+use Latte\Attributes\TemplateFunction;
+
+class ArticlePresenter extends Nette\Application\UI\Presenter
+{
+	#[TemplateFilter]
+	public function money(float $val): string
+	{
+		return round($val) . ' Kč';
+	}
+
+	#[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;
@@ -236,33 +300,41 @@ final class LatteExtension extends Latte\Extension
 	public function getFilters(): array
 	{
 		return [
+			'money' => fn($val) => number_format($val, 2, ',', ' ') . ' Kč',
 			'timeAgoInWords' => $this->filterTimeAgoInWords(...),
-			'money' => $this->filterMoney(...),
 			// ...
 		];
 	}
 
 	public function getFunctions(): array
 	{
 		return [
+			'stars' => fn($rating) => str_repeat('⭐', $rating),
 			'canEditArticle' =>
 				fn($article) => $this->facade->canEditArticle($article, $this->user->getId()),
 			// ...
 		];
 	}
 
+	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í
 ----------

nette/cs/vulnerability-protection.texy

@@ -48,18 +48,7 @@ Nette Framework **automaticky chrání formuláře a signály v presenterech** p
 $form->allowCrossOrigin();
 ```
 
-nebo v případě signálu přidejte anotaci `@crossOrigin`:
-
-```php
-/**
- * @crossOrigin
- */
-public function handleXyz()
-{
-}
-```
-
-V Nette Application 3.2 můžete použít také atributy:
+nebo v případě signálu přidejte atribut:
 
 ```php
 use Nette\Application\Attributes\Requires;