Презентеры
**********

<div class=perex>

Научимся создавать презентеры и шаблоны в Nette. После прочтения этой статьи вы узнаете:

- как работает презентер
- что такое постоянные параметры
- как отрендерить шаблон

</div>

[Мы уже знаем |how-it-works#Nette-Application], что презентер это класс, который представляет конкретную страницу веб-приложения, такую как главная страница; страница товара в интернет-магазине; форма авторизации; карта сайта и т. д. Приложение может иметь от одного до тысячи презентеров. В других фреймворках они также известны как контроллеры.

Обычно термин *презентер* соотносится с потомком класса [api:Nette\Application\UI\Presenter], который подходит для веб-интерфейсов. Мы обсудим этот класс в оставшейся части этой главы. В общем смысле, презентер — это любой объект, реализующий интерфейс [api:Nette\Application\IPresenter].


Жизненный цикл презентера .[#toc-life-cycle-of-presenter]
=========================================================

Задача презентера — обработать запрос и вернуть ответ (это может быть HTML-страница, изображение, перенаправление и т. д.).

Итак, в начале — запрос. Это не непосредственно HTTP-запрос, а объект [api:Nette\Application\Request], в который HTTP-запрос был преобразован с помощью маршрутизатора. Обычно мы не сталкиваемся с этим объектом, потому что презентер ловко делегирует обработку запроса специальным методам, которые мы сейчас увидим.

[* lifecycle.svg *] *** *Жизненный цикл презентера* .<>

На рисунке показан список методов, которые вызываются последовательно сверху вниз, если они существуют. Все они необязательные, мы можем иметь совершенно пустой презентер без единого метода и построить на нем простой статический веб.


`__construct()`
---------------

Конструктор не совсем относится к жизненному циклу презентера, поскольку вызывается в момент создания объекта. Но мы упоминаем его из-за важности, поскольку он используется для передачи зависимостей.

Презентер не должен заботиться о бизнес-логике приложения, писать и читать из базы данных, выполнять вычисления и т. д. Это задача для классов из слоя, который мы называем моделью. Например, класс `ArticleRepository` может отвечать за загрузку и сохранение статей. Для того чтобы презентер мог его использовать, он [передается с помощью внедрения зависимостей |dependency-injection:passing-dependencies]:


```php
class ArticlePresenter extends Nette\Application\UI\Presenter
{
	public function __construct(
		private ArticleRepository $articles,
	) {
	}
}
```


`startup()`
-----------

Сразу после получения запроса вызывается метод `startup()`. Вы можете использовать его для инициализации свойств, проверки привилегий пользователя и т. д. Требуется всегда вызывать предка `parent::startup()`.


`action<Action>(args...)` .{toc: action<Action>()}
--------------------------------------------------

Аналогичен методу `render<View>()`. В то время как `render<View>()` предназначена для подготовки данных для определенного шаблона, который впоследствии рендерится, в `action<Action>()` запрос обрабатывается без последующего рендеринга шаблона. Например, данные обрабатываются, пользователь входит или выходит из системы и так далее, а затем [перенаправляется в другое место |#Redirection].

Важно, что `action<Action>()` вызывается перед `render<View>()`, поэтому внутри него мы можем, возможно, изменить следующий ход жизненного цикла, т. е. изменить шаблон, который будет отображаться, а также метод `render<View>()`, который будет вызываться, используя `setView('otherView')`.

В метод передаются параметры из запроса. Можно и рекомендуется указывать типы для параметров, например `actionShow(int $id, ?string $slug = null)` — если параметр `id` отсутствует или если он не является целым числом, презентер возвращает [ошибку 404|#Error-404-etc] и завершает операцию.


`handle<Signal>(args...)` .{toc: handle<Signal>()}
--------------------------------------------------

Этот метод обрабатывает так называемые сигналы, о которых мы поговорим в главе о [Компонентах |components#Signal]. Он предназначен в основном для компонентов и обработки AJAX-запросов.

Параметры передаются методу, как в случае `action<Action>()`, включая проверку типа.


`beforeRender()`
----------------

Метод `beforeRender`, как следует из названия, вызывается перед каждым методом `render<View>()`. Используется для общей настройки шаблона, передачи переменных для верстки и так далее.


`render<View>(args...)` .{toc: render<View>()}
----------------------------------------------

Место, где мы готовим шаблон к последующему рендерингу, передаем ему данные и т. д.

Параметры передаются методу, как в случае `action<Action>()`, включая проверку типа.

```php
public function renderShow(int $id): void
{
	// мы получаем данные из модели и передаем их в шаблон
	$this->template->article = $this->articles->getById($id);
}
```


`afterRender()`
---------------

Метод `afterRender`, как следует из названия, вызывается после каждого метода `render<View>()`. Он используется довольно редко.


`shutdown()`
------------

Вызывается в конце жизненного цикла презентера.


**Хороший совет, прежде чем мы продолжим**. Как вы видите, презентер может обрабатывать больше действий/просмотров, т. е. имеют больше методов `render<View>()`. Но мы рекомендуем разрабатывать презентеры с одним или как можно меньшим количеством действий.


Отправка ответа .[#toc-sending-a-response]
==========================================

Обычно ответом ведущего является [рендеринг шаблона с HTML-страницей|templates], но это также может быть отправка файла, JSON или даже перенаправление на другую страницу.

В любой момент жизненного цикла мы можем использовать один из следующих методов для отправки ответа и завершения работы презентера:

- [Перенаправления |#Redirection] `redirect()`, `redirectPermanent()`, `redirectUrl()` и `forward()`.
- `error()` завершает работу презентера [из-за ошибки |#Error-404-etc].
- `sendJson($data)` выходит из презентера и отправляет данные в формате JSON
- `sendTemplate()` завершает работу презентера и сразу же выполняет рендеринг шаблона
- `sendResponse($response)` выходит из презентера и отправляет [собственный ответ |#Ответы].
- `terminate()` завершает работу презентера без ответа

**Сейчас что-то важное**: если мы явно не говорим, какой ответ должен отправить презентер, ответом будет [рендеринг шаблонов |#Рендеринг шаблонов] HTML. Почему? Ну, потому что в 99% случаев мы хотим отрендерить шаблон, поэтому презентер принимает такое поведение по умолчанию и хочет облегчить нашу работу.


Создание ссылок .[#toc-creating-links]
======================================

У презентера есть метод `link()`, который используется для создания URL-ссылок на другие презентеры. Первым параметром является целевой презентер и действие, затем следуют аргументы, которые могут быть переданы в виде массива:

```php
$url = $this->link('Product:show', $id);

$url = $this->link('Product:show', [$id, 'lang' => 'en']);
```

В шаблоне мы создаем ссылки на другие презентеры и действия следующим образом:

```latte
<a n:href="Product:show $id">страница товара</a>
```

Просто напишите знакомую пару `Presenter:action` вместо реального URL и включите любые параметры. Хитрость заключается в `n:href`, который говорит, что этот атрибут будет обработан Latte и сгенерирует настоящий URL. В Nette вам вообще не нужно думать об URL-адресах, только о презентерах и действиях.

Для получения дополнительной информации см. [Создание ссылок |creating-links].


Перенаправление .[#toc-redirection]
===================================

Для перехода к другому презентеру используются методы `redirect()` и `forward()`, которые имеют очень похожий синтаксис с методом [link() |#Creating-Links].

Функция `forward()` переключает на новый презентер немедленно без перенаправления HTTP:

```php
$this->forward('Product:show');
```

Пример так называемого временного перенаправления с HTTP-кодом 302 (или 303, если текущий метод запроса - POST):

```php
$this->redirect('Product:show', $id);
```

Для достижения постоянного перенаправления с HTTP-кодом 301 используйте:

```php
$this->redirectPermanent('Product:show', $id);
```

Вы можете перенаправить на другой URL вне приложения, используя метод `redirectUrl()`. HTTP-код может быть указан в качестве второго параметра, по умолчанию это 302 (или 303, если текущий метод запроса - POST):

```php
$this->redirectUrl('https://nette.org');
```

Перенаправление немедленно завершает жизненный цикл презентера, выбрасывая так называемое исключение молчаливого завершения `Nette\Application\AbortException`.

Перед перенаправлением можно отправить [флэш-сообщение |#Flash-Messages], которое будет отображаться в шаблоне после перенаправления.


Флэш-сообщения .[#toc-flash-messages]
=====================================

Это сообщения, которые обычно информируют о результате операции. Важной особенностью флэш-сообщений является то, что они доступны в шаблоне даже после перенаправления. Даже после отображения они будут оставаться живыми еще 30 секунд — например, на случай, если пользователь непреднамеренно обновит страницу — сообщение не будет потеряно.

Просто вызовите метод [flashMessage() |api:Nette\Application\UI\Control::flashMessage()] и презентер позаботится о передаче сообщения в шаблон. Первый аргумент — текст сообщения, а второй необязательный аргумент — его тип (ошибка, предупреждение, информация и т. д.). Метод `flashMessage()` возвращает экземпляр флэш-сообщения, чтобы мы могли добавить дополнительную информацию.

```php
$this->flashMessage('Item was removed.');
$this->redirect(/* ... */);
```

В шаблоне эти сообщения доступны в переменной `$flashes` как объекты `stdClass`, которые содержат свойства `message` (текст сообщения), `type` (тип сообщения) и могут содержать уже упомянутую информацию о пользователе. Мы выводим их следующим образом:

```latte
{foreach $flashes as $flash}
	<div class="flash {$flash->type}">{$flash->message}</div>
{/foreach}
```


Ошибка 404 и т. д. .[#toc-error-404-etc]
========================================

Когда мы не можем выполнить запрос, потому что, например, статья, которую мы хотим отобразить, не существует в базе данных, мы выбросим ошибку 404, используя метод `error(?string $message = null, int $httpCode = 404)`, который представляет HTTP-ошибку 404:

```php
public function renderShow(int $id): void
{
	$article = $this->articles->getById($id);
	if (!$article) {
		$this->error();
	}
	// ...
}
```

Код ошибки HTTP может быть передан в качестве второго параметра, по умолчанию это 404. Метод работает, выбрасывая исключение `Nette\Application\BadRequestException`, после чего `Application` передает управление презентеру ошибки. Его задача — отобразить страницу, информирующую об ошибке.
Преселектор ошибок устанавливается в [конфигурация приложения |configuration].


Отправка JSON .[#toc-sending-json]
==================================

Пример действия-метода, который отправляет данные в формате JSON и выходит из ведущего:

```php
public function actionData(): void
{
	$data = ['hello' => 'nette'];
	$this->sendJson($data);
}
```


Параметры запроса .[#toc-request-parameters]
============================================

Ведущий, как и каждый компонент, получает свои параметры из HTTP-запроса. Их значения могут быть получены с помощью метода `getParameter($name)` или `getParameters()`. Значения представляют собой строки или массивы строк, по сути, необработанные данные, полученные непосредственно из URL.

Для большего удобства рекомендуется сделать параметры доступными через свойства. Для этого достаточно аннотировать их с помощью `#[Parameter]` атрибутом:

```php
use Nette\Application\Attributes\Parameter;  // эта строка очень важна

class HomePresenter extends Nette\Application\UI\Presenter
{
	#[Parameter]
	public string $theme; // должна быть публичной
}
```

Для свойств рекомендуется указывать тип данных (например, `string`). В этом случае Nette будет автоматически приводить значение на его основе. Значения параметров также могут быть [проверены |#Validation of Parameters].

При создании ссылки можно непосредственно задать значение параметров:

```latte
<a n:href="Home:default theme: dark">click</a>
```


Постоянные параметры .[#toc-persistent-parameters]
==================================================

Постоянные параметры используются для сохранения состояния между различными запросами. Их значение остается неизменным даже после нажатия на ссылку. В отличие от данных сессии, они передаются в URL. Это происходит полностью автоматически, поэтому нет необходимости явно указывать их в `link()` или `n:href`.

Пример использования? У вас есть многоязычное приложение. Фактический язык - это параметр, который всегда должен быть частью URL. Но было бы невероятно утомительно указывать его в каждой ссылке. Поэтому вы сделаете его постоянным параметром с именем `lang`, и он сам себя перенесет. Круто!

Создать постоянный параметр в Nette очень просто. Просто создайте публичное свойство и пометьте его атрибутом: (ранее использовалось `/** @persistent */` ).

```php
use Nette\Application\Attributes\Persistent; // эта строка важна

class ProductPresenter extends Nette\Application\UI\Presenter
{
	#[Persistent]
	public string $lang; // должны быть публичными
}
```

Если `$this->lang` имеет значение, например, `'en'`, то ссылки, созданные с помощью `link()` или `n:href`, также будут содержать параметр `lang=en`. И когда ссылка будет щелкнута, она снова станет `$this->lang = 'en'`.

Для свойств рекомендуется указывать тип данных (например, `string`), а также можно указать значение по умолчанию. Значения параметров могут быть [проверены |#Validation of Parameters].

Постоянные параметры по умолчанию передаются между всеми действиями данного ведущего. Чтобы передать их между несколькими ведущими, необходимо определить их либо:

- в общем предке, от которого наследуют ведущие
- в трейте, который используют ведущие:

```php
trait LanguageAware
{
	#[Persistent]
	public string $lang;
}

class ProductPresenter extends Nette\Application\UI\Presenter
{
	use LanguageAware;
}
```

Вы можете изменить значение постоянного параметра при создании ссылки:

```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>
```


Интерактивные компоненты .[#toc-interactive-components]
=======================================================

У презентеров есть встроенная система компонентов. Компоненты — это отдельные многократно используемые единицы, которые мы помещаем в презентеры. Это могут быть [формы|forms:in-presenter], сетки данных, меню, в общем, всё, что имеет смысл использовать многократно.

Как размещаются и впоследствии используются компоненты в презентере? Это объясняется в главе [компоненты|components]. Вы даже узнаете, какое отношение они имеют к Голливуду.

Где можно приобрести некоторые компоненты? На странице [Componette |https://componette.org] вы можете найти некоторые компоненты с открытым исходным кодом и другие дополнения для Nette, которые создаются и распространяются сообществом фреймворка Nette.


Углубляемся .[#toc-going-deeper]
================================

.[tip]
Того, что мы показали до сих пор в этой главе, вероятно, будет достаточно. Следующие строки предназначены для тех, кто интересуется презентерами досконально и хочет знать всё.


Валидация параметров .[#toc-validation-of-parameters]
-----------------------------------------------------

Значения [параметров запроса |#request 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]
------------------------------------------------------------------------

Запрос, который обрабатывает ведущий, представляет собой объект [api:Nette\Application\Request] и возвращается методом ведущего `getRequest()`.

Вы можете сохранить текущий запрос в сессии или восстановить его из сессии и позволить ведущему выполнить его снова. Это удобно, например, когда пользователь заполняет форму, а его логин истекает. Чтобы не потерять данные, перед перенаправлением на страницу входа в систему мы сохраняем текущий запрос в сессии с помощью метода `$reqId = $this->storeRequest()`, который возвращает идентификатор в виде короткой строки и передает его в качестве параметра презентеру входа в систему.

После входа в систему мы вызываем метод `$this->restoreRequest($reqId)`, который забирает запрос у сессии и пересылает его ей. Метод проверяет, что запрос был создан тем же пользователем, который сейчас вошел в систему. Если другой пользователь вошел в систему или ключ недействителен, он ничего не делает, и программа продолжает работу.

См. главу [Как вернуться на предыдущую страницу |best-practices:restore-request].


Канонизация .[#toc-canonization]
--------------------------------

У презентеров есть одна действительно замечательная функция, которая улучшает SEO. Они автоматически предотвращают существование дублирующего контента на разных URL-адресах. Если несколько URL-адресов ведут к определенному месту назначения, например. `/index` и `/index?page=1`, фреймворк назначает один из них основным (каноническим) и перенаправляет на него остальные с помощью HTTP-кода 301. Благодаря этому поисковые системы не индексируют страницы дважды и не ослабляют их рейтинг.

Этот процесс называется канонизацией. Канонический URL — это URL, сгенерированный [маршрутом |routing], обычно первый подходящий маршрут в коллекции.

Канонизация включена по умолчанию и может быть отключена с помощью `$this->autoCanonicalize = false`.

Перенаправление не происходит при запросе AJAX или POST, так как это приведет к потере данных или не принесет никакой пользы для SEO.

Вы также можете вызвать канонизацию вручную с помощью метода `canonicalize()`, который, как и метод `link()`, получает в качестве аргументов презентера, действия и параметры. Он создает ссылку и сравнивает её с текущим URL. Если они отличаются, то происходит перенаправление на сгенерированную ссылку.

```php
public function actionShow(int $id, ?string $slug = null): void
{
	$realSlug = $this->facade->getSlugForId($id);
	// перенаправляет, если $slug отличается от $realSlug
	$this->canonicalize('Product:show', [$id, $realSlug]);
}
```


События .[#toc-events]
----------------------

Помимо методов `startup()`, `beforeRender()` и `shutdown()`, которые вызываются в рамках жизненного цикла презентера, можно определить другие функции, которые будут вызываться автоматически. Презентер определяет так называемые [события |nette:glossary#Events], а вы добавляете их обработчики в массивы `$onStartup`, `$onRender` и `$onShutdown`.

```php
class ArticlePresenter extends Nette\Application\UI\Presenter
{
	public function __construct()
	{
		$this->onStartup[] = function () {
			// ...
		};
	}
}
```

Обработчики в массиве `$onStartup` вызываются непосредственно перед методом `startup()`, затем `$onRender` между `beforeRender()` и `render<View>()` и, наконец, `$onShutdown` непосредственно перед `shutdown()`.


Ответы .[#toc-responses]
------------------------

Ответ, возвращаемый презентером, представляет собой объект, реализующий интерфейс [api:Nette\Application\Response]. Есть несколько готовых ответов:

- [api:Nette\Application\Responses\CallbackResponse] — посылает обратный вызов
- [api:Nette\Application\Responses\FileResponse] — посылает файл
- [api:Nette\Application\Responses\ForwardResponse] — forward ()
- [api:Nette\Application\Responses\JsonResponse] — посылает JSON
- [api:Nette\Application\Responses\RedirectResponse] — перенаправляет
- [api:Nette\Application\Responses\TextResponse] — посылает текст
- [api:Nette\Application\Responses\VoidResponse] — пустой ответ

Ответы отправляются методом `sendResponse()`:

```php
use Nette\Application\Responses;

// Обычный текст
$this->sendResponse(new Responses\TextResponse('Hello Nette!'));

// Отправляет файл
$this->sendResponse(new Responses\FileResponse(__DIR__ . '/invoice.pdf', 'Invoice13.pdf'));

// Отправляет обратный вызов
$callback = function (Nette\Http\IRequest $httpRequest, Nette\Http\IResponse $httpResponse) {
	if ($httpResponse->getHeader('Content-Type') === 'text/html') {
		echo '<h1>Hello</h1>';
	}
};
$this->sendResponse(new Responses\CallbackResponse($callback));
```


Ограничение доступа с помощью `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2}
---------------------------------------------------------------------------------------------------------

Атрибут `#[Requires]` предоставляет расширенные возможности для ограничения доступа к ведущим и их методам. С его помощью можно указать HTTP-методы, потребовать AJAX-запросы, ограничить доступ к одному и тому же источнику и ограничить доступ только пересылкой. Атрибут может применяться как к классам ведущих, так и к отдельным методам, таким как `action<Action>()`, `render<View>()`, `handle<Signal>()`, и `createComponent<Name>()`.

Вы можете указать эти ограничения:
- на методы HTTP: `#[Requires(methods: ['GET', 'POST'])]`
- требующих AJAX-запроса: `#[Requires(ajax: true)]`
- доступ только из одного источника: `#[Requires(sameOrigin: true)]`
- доступ только через переадресацию: `#[Requires(forward: true)]`
- ограничения на определенные действия: `#[Requires(actions: 'default')]`

Подробнее см. в разделе [Как использовать Requires атрибут |best-practices:attribute-requires].


Проверка метода HTTP .[#toc-http-method-check]
----------------------------------------------

В Nette ведущие автоматически проверяют HTTP-метод каждого входящего запроса, прежде всего, из соображений безопасности. По умолчанию разрешены методы `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`.

Если вы хотите разрешить дополнительные методы, такие как `OPTIONS`, вы можете использовать атрибут `#[Requires]` атрибут (из Nette Application v3.2):

```php
#[Requires(methods: ['GET', 'POST', 'HEAD', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'])]
class MyPresenter extends Nette\Application\UI\Presenter
{
}
```

В версии 3.1 проверка осуществляется в методе `checkHttpMethod()`, который проверяет, включен ли указанный в запросе метод в массив `$presenter->allowedMethods`. Добавьте метод следующим образом:

```php
class MyPresenter extends Nette\Application\UI\Presenter
{
    protected function checkHttpMethod(): void
    {
        $this->allowedMethods[] = 'OPTIONS';
        parent::checkHttpMethod();
    }
}
```

Важно подчеркнуть, что если вы разрешаете метод `OPTIONS`, то должны правильно обработать его и в своем презентаторе. Этот метод часто используется в качестве так называемого preflight-запроса, который браузеры автоматически отправляют перед фактическим запросом, когда необходимо определить, разрешен ли запрос с точки зрения политики CORS (Cross-Origin Resource Sharing). Если разрешить этот метод, но не реализовать соответствующий ответ, это может привести к несоответствиям и потенциальным проблемам безопасности.


Дальнейшее чтение .[#toc-further-reading]
=========================================

- [Инжектирование методов и атрибутов |best-practices:inject-method-attribute]
- [Составление презентеров из признаков |best-practices:presenter-traits]
- [Передача параметров в презентеры |best-practices:passing-settings-to-presenters]
- [Как вернуться на предыдущую страницу |best-practices:restore-request]