persistent parameters: improved info

Author: dg

application/bg/components.texy

@@ -233,31 +233,34 @@ $this->redirect(/* ... */); // пренасочване
 Постоянни параметри .[#toc-persistent-parameters]
 =================================================
 
-Често е необходимо да се запази даден параметър в компонент за целия период на експлоатация на компонента. Това може да бъде например номер на страница в странирането. Този параметър трябва да бъде отбелязан като постоянен с помощта на анотацията `@persistent`.
+Постоянните параметри се използват за поддържане на състоянието на компонентите между различните заявки. Тяхната стойност остава същата дори след щракване върху връзката. За разлика от данните за сесията, те се прехвърлят в URL адреса. И се прехвърлят автоматично, включително връзките, създадени в други компоненти на същата страница.
+
+Например, имате компонент за страниране на съдържание. На една страница може да има няколко такива компонента. И искате всички компоненти да останат на текущата си страница, когато щракнете върху връзката. Затова правим номера на страницата (`page`) постоянен параметър.
+
+Създаването на постоянен параметър е изключително лесно в Nette. Просто създайте публично свойство и го маркирайте с атрибута: (преди се използваше `/** @persistent */` )
 
 ```php
-class PollControl extends Control
+use Nette\Application\Attributes\Persistent;
+
+class PaginatingControl extends Control
 {
-	/** @persistent */
-	public int $page = 1;
+	#[Persistent]
+	public int $page = 1; // трябва да бъдат публични
 }
 ```
 
-Този параметър ще се предава автоматично във всяка връзка като параметър `GET`, докато потребителят напусне страницата с този компонент.
+Препоръчваме ви да включите типа данни (например `int`) към свойството, като можете да включите и стойност по подразбиране. Стойностите на параметрите могат да бъдат [валидирани |#Validation of Persistent Parameters].
 
-.[caution]
-Никога не се доверявайте сляпо на постоянни параметри, тъй като те могат лесно да бъдат подправени (чрез презаписване на URL адреса). Проверете например дали номерът на страницата е в правилния интервал.
+Можете да променяте стойността на постоянен параметър, когато създавате връзка:
 
-В PHP 8 можете също така да използвате атрибути, за да маркирате постоянни параметри:
+```latte
+<a n:href="this page: $page + 1">next</a>
+```
 
-```php
-use Nette\Application\Attributes\Persistent;
+Или може да бъде *ресетнат*, т.е. да бъде премахнат от URL адреса. След това той ще приеме стойността си по подразбиране:
 
-class PollControl extends Control
-{
-	#[Persistent]
-	public int $page = 1;
-}
+```latte
+<a n:href="this page: null">reset</a>
 ```
 
 
@@ -378,7 +381,7 @@ interface PollControlFactory
 
 1) може да се показва в шаблон
 2) той знае каква част от себе си да покаже по време на [заявката AJAX |ajax#invalidation] (фрагменти)
-3) може да съхранява състоянието си в URL (параметри за устойчивост).
+3) има възможност да съхранява състоянието си в URL (постоянни параметри).
 4) има възможност да реагира на действията (сигналите) на потребителя.
 5) създава йерархична структура (където коренът е главният).
 
@@ -403,6 +406,33 @@ Nette\ComponentModel\Component  { IComponent }
 [* lifecycle-component.svg *] *** * Жизнен цикъл на компонента* .<>
 
 
+Утвърждаване на постоянни параметри .[#toc-validation-of-persistent-parameters]
+-------------------------------------------------------------------------------
+
+Стойностите на [постоянните параметри, |#persistent parameters] получени от URL адреси, се записват в свойствата чрез метода `loadState()`. Той също така проверява дали типът данни, зададен за свойството, съвпада, в противен случай ще отговори с грешка 404 и страницата няма да бъде показана.
+
+Никога не се доверявайте сляпо на постоянните параметри, защото те лесно могат да бъдат пренаписани от потребителя в URL адреса. Например, така проверяваме дали номерът на страницата `$this->page` е по-голям от 0. Добър начин да направите това е да презапишете метода `loadState()`, споменат по-горе:
+
+```php
+class PaginatingControl extends Control
+{
+	#[Persistent]
+	public int $page = 1;
+
+	public function loadState(array $params): void
+	{
+		parent::loadState($params); // тук се задава $this->page
+		// следва проверката на потребителската стойност:
+		if ($this->page < 1) {
+			$this->error();
+		}
+	}
+}
+```
+
+Противоположният процес, т.е. събирането на стойности от постоянни пропъртита, се обработва от метода `saveState()`.
+
+
 Сигнали в дълбочина .[#toc-signals-in-depth]
 --------------------------------------------
 

application/bg/presenters.texy

@@ -239,46 +239,54 @@ public function actionData(): void
 Постоянни параметри .[#toc-persistent-parameters]
 =================================================
 
-Постоянните параметри се **предават автоматично** във връзките. Това означава, че не е необходимо да ги посочваме изрично във всеки `link()` или `n:href` в шаблона, но те все пак ще бъдат предадени.
+Постоянните параметри се използват за поддържане на състоянието между различните заявки. Стойността им остава същата дори след щракване върху връзката. За разлика от данните за сесията, те се предават в URL адреса. Това става напълно автоматично, така че не е необходимо да ги посочвате изрично в `link()` или `n:href`.
 
-Ако приложението ви има няколко езикови версии, текущият език е параметър, който винаги трябва да бъде част от URL адреса. И би било изключително досадно да го споменаваме във всяка връзка. При Nette това не е необходимо. Затова просто отбелязваме параметъра `lang` като постоянен:
+Пример за използване? Имате многоезично приложение. Действителният език е параметър, който трябва да бъде част от URL адреса по всяко време. Но би било изключително досадно да го включвате във всяка връзка. Затова го правите постоянен параметър с име `lang` и той ще се пренася сам. Страхотно!
+
+Създаването на постоянен параметър е изключително лесно в Nette. Просто създайте публично свойство и го маркирайте с атрибута: (преди се използваше `/** @persistent */` )
 
 ```php
+use Nette\Application\Attributes\Persistent;
+
 class ProductPresenter extends Nette\Application\UI\Presenter
 {
-	/** @persistent */
-	public string $lang;
+	#[Persistent]
+	public string $lang; // трябва да бъдат публични
 }
 ```
 
-Ако текущата стойност на параметъра `lang` е `'en'`, тогава URL адресът, създаден с `link()` или `n:href` в шаблона, ще съдържа `lang=en`. Перфектно!
-
-Можем обаче да добавим и параметъра `lang` и по този начин да променим стойността му:
-
-```latte
-<a n:href="Product:show $id, lang: en">подробности на английском</a>
-```
-
-Или пък можем да го изтрием, като му зададем стойност null:
-
-```latte
-<a n:href="Product:show $id, lang: null">нажмите здесь</a>
-```
+Ако `$this->lang` има стойност като `'en'`, то връзките, създадени с помощта на `link()` или `n:href`, ще съдържат и параметъра `lang=en`. И когато върху връзката се щракне, тя отново ще бъде `$this->lang = 'en'`.
 
-Една постоянна променлива трябва да бъде декларирана като публична. Можем да зададем и стойност по подразбиране. Ако параметърът има същата стойност като тази по подразбиране, той няма да бъде включен в URL адреса.
+За свойствата препоръчваме да включите типа данни (например `string`), а също така можете да включите стойност по подразбиране. Стойностите на параметрите могат да бъдат [валидирани |#Validation of Persistent Parameters].
 
-Постоянството отразява йерархията на класовете на презентаторите, така че параметър, дефиниран в конкретен презентатор или черта, се предава автоматично на всеки презентатор, който наследява от него или използва същата черта.
+Постоянните параметри се предават между всички действия на даден презентатор по подразбиране. За да ги предадете между няколко водещи, трябва да ги дефинирате или:
 
-В PHP 8 можете също така да използвате атрибути, за да маркирате постоянни параметри:
+- в общ предшественик, от който презентаторите наследяват
+- в чертата, която презентаторите използват:
 
 ```php
-use Nette\Application\Attributes\Persistent;
-
-class ProductPresenter extends Nette\Application\UI\Presenter
+trait LangAware
 {
 	#[Persistent]
 	public string $lang;
 }
+
+class ProductPresenter extends Nette\Application\UI\Presenter
+{
+	use LangAware;
+}
+```
+
+Можете да променяте стойността на постоянен параметър, когато създавате връзка:
+
+```latte
+<a n:href="Product:show $id, lang: cs">detail in Czech</a>
+```
+
+Или може да бъде *ресетнат*, т.е. да бъде премахнат от URL адреса. След това той ще приеме стойността си по подразбиране:
+
+```latte
+<a n:href="Product:show $id, lang: null">click</a>
 ```
 
 
@@ -302,7 +310,32 @@ class ProductPresenter extends Nette\Application\UI\Presenter
 Изисквания и параметри .[#toc-requirement-and-parameters]
 ---------------------------------------------------------
 
-Заявката, която се обработва от водещия, е обект [api:Nette\Application\Request] и се връща от метода на водещия `getRequest()`. Той включва масив от параметри, всеки от които принадлежи или на някой компонент, или директно на водещия (който всъщност също е компонент, макар и специален). По този начин Nette преразпределя параметрите и ги прехвърля между отделните компоненти (и водещия) чрез извикване на метода `loadState(array $params)`, който е описан по-подробно в главата [Компоненти |components]. Параметрите могат да се извличат чрез метода `getParameters(): array`, а поотделно - чрез `getParameter($name)`. Стойностите на параметрите са низове или масиви от низове, предимно необработени данни, получени директно от URL.
+Заявката, която се обработва от водещия, е обектът [api:Nette\Application\Request] и се връща от метода на водещия `getRequest()`. Тя включва масив от параметри и всеки от тях принадлежи или на някой от компонентите, или директно на водещия (който всъщност също е компонент, макар и специален). Затова Nette преразпределя параметрите и преминава между отделните компоненти (и водещия), като извиква метода `loadState(array $params)`. Параметрите могат да бъдат получени чрез метода `getParameters(): array`, а поотделно чрез `getParameter($name)`. Стойностите на параметрите са низове или масиви от низове, те по същество са необработени данни, получени директно от URL адреса.
+
+
+Утвърждаване на постоянни параметри .[#toc-validation-of-persistent-parameters]
+-------------------------------------------------------------------------------
+
+Стойностите на [постоянните параметри, |#persistent parameters] получени от URL адреси, се записват в свойствата чрез метода `loadState()`. Той също така проверява дали типът данни, посочен в свойството, съвпада, в противен случай ще отговори с грешка 404 и страницата няма да бъде показана.
+
+Никога не се доверявайте сляпо на постоянните параметри, тъй като те лесно могат да бъдат пренаписани от потребителя в URL адреса. Например, така проверяваме дали `$this->lang` е сред поддържаните езици. Добър начин да направите това е да пренастроите метода `loadState()`, споменат по-горе:
+
+```php
+class ProductPresenter extends Nette\Application\UI\Presenter
+{
+	#[Persistent]
+	public string $lang;
+
+	public function loadState(array $params): void
+	{
+		parent::loadState($params); // тук се задава $this->lang
+		// следва проверката на потребителската стойност:
+		if (!in_array($this->lang, ['en', 'cs'])) {
+			$this->error();
+		}
+	}
+}
+```
 
 
 Запазване и възстановяване на заявка .[#toc-save-and-restore-the-request]