Elementy interaktywne
*********************

<div class=perex>

Komponenty to samodzielne obiekty wielokrotnego użytku, które wstawiamy do stron. Mogą to być formularze, datagridy, ankiety, w rzeczywistości wszystko, co ma sens, aby używać wielokrotnie. Zobaczmy:

- jak używać komponentów?
- jak je napisać?
- co to są sygnały?

</div>

Nette posiada wbudowany system komponentów. Memordziści mogą znać coś podobnego z Delphi lub ASP.NET Web Forms, a React lub Vue.js jest zbudowany na czymś zdalnie podobnym. W świecie frameworków PHP jest to jednak ewenement.

Jednak komponenty w zasadniczy sposób wpływają na podejście do tworzenia aplikacji. W rzeczywistości można komponować strony z gotowych jednostek. Czy potrzebujesz datagridu w swojej administracji? Można go znaleźć na [Componette |https://componette.org/search/component], repozytorium open-source'owych dodatków (nie tylko komponentów) dla Nette, i po prostu wstawić do prezentera.

W prezenterze można zawrzeć dowolną liczbę komponentów. A do niektórych komponentów można wstawić inne komponenty. Tworzy to drzewo komponentów z prezenterem jako korzeniem.


Metody fabryczne .[#toc-factory-methods]
========================================

Jak komponenty są wstawiane do prezentera, a następnie wykorzystywane? Zazwyczaj z wykorzystaniem metod fabrycznych.

Fabryka komponentów jest eleganckim sposobem tworzenia komponentów tylko wtedy, gdy są one rzeczywiście potrzebne (leniwe / na żądanie). Cała magia tkwi w implementacji metody o nazwie `createComponent<Name>()`gdzie `<Name>` jest nazwą tworzonego komponentu, który tworzy i zwraca komponent.

```php .{file:DefaultPresenter.php}
class DefaultPresenter extends Nette\Application\UI\Presenter
{
	protected function createComponentPoll(): PollControl
	{
		$poll = new PollControl;
		$poll->items = $this->item;
		return $poll;
	}
}
```

Ponieważ wszystkie komponenty są tworzone w osobnych metodach, kod zyskuje na przejrzystości.

.[note]
Nazwy komponentów zawsze zaczynają się od małej litery, nawet jeśli w nazwie metody są pisane wielką literą.

Nigdy nie wywołujemy fabryk bezpośrednio, dzwonią one do siebie przy pierwszym użyciu komponentu. Dzięki temu komponent jest tworzony w odpowiednim czasie i tylko wtedy, gdy jest rzeczywiście potrzebny. Jeśli nie korzystamy z komponentu (np. podczas żądania AJAX, gdy przekazywana jest tylko część strony, lub podczas buforowania szablonu), nie jest on w ogóle tworzony i oszczędzamy wydajność serwera.

```php .{file:DefaultPresenter.php}
// przechodzimy do komponentu i jeśli był to pierwszy raz,
// wywołaj funkcję createComponentPoll(), aby go stworzyć
$poll = $this->getComponent('poll');
// alternatywna składnia: $poll = $this['poll'];
```

Możliwe jest renderowanie komponentu w szablonie za pomocą znacznika [{control} |#Rendering], dlatego nie ma potrzeby ręcznego przekazywania komponentów do szablonu.

```latte
<h2>Please Vote</h2>

{control poll}
```


Styl hollywoodzki .[#toc-hollywood-style]
=========================================

Komponenty powszechnie wykorzystują jedną świeżą technikę, którą lubimy nazywać stylem hollywoodzkim. Na pewno znacie skrzydlate zdanie, które tak często słyszą osoby biorące udział w przesłuchaniach do filmów: "Nie dzwoń do nas, my zadzwonimy do ciebie". I właśnie o to chodzi.

Bo w Nette, zamiast konieczności ciągłego zadawania pytań ("czy formularz został przesłany?", "czy był ważny?" lub "czy użytkownik nacisnął ten przycisk?"), mówisz frameworkowi "kiedy to się stanie, wywołaj tę metodę" i pozostawiasz mu resztę pracy. Jeśli programujesz w JavaScript, jesteś zaznajomiony z tym stylem programowania. Piszesz funkcje, które są wywoływane w momencie wystąpienia zdarzenia. A język przekazuje im odpowiednie parametry.

To całkowicie zmienia sposób myślenia o pisaniu aplikacji. Im więcej zadań możesz zostawić ramom, tym mniej pracy musisz wykonać. I tym mniej można pominąć, np.


Pisanie komponentu .[#toc-how-to-write-a-component]
===================================================

Przez komponent zwykle rozumiemy potomka klasy [api:Nette\Application\UI\Control]. (Dokładniej byłoby użyć terminu "kontrole", ale "kontrole" mają zupełnie inne znaczenie w języku angielskim i "komponenty" przejęły je). Sam prezenter [api:Nette\Application\UI\Presenter] zresztą też jest potomkiem klasy `Control`.

```php .{file:PollControl.php}
use Nette\Application\UI\Control;

class PollControl extends Control
{
}
```


Rendering .[#toc-rendering]
===========================

Wiemy już, że znacznik `{control componentName}` służy do renderowania komponentu. W rzeczywistości wywołuje to metodę `render()` komponentu, w której wykonamy renderowanie. Mamy, podobnie jak w Presenterze, [szablon Latte |templates] w zmiennej `$this->template`, do którego przekazujemy parametry. W przeciwieństwie do prezentera, musimy podać plik szablonu i zlecić jego renderowanie:

```php .{file:PollControl.php}
public function render(): void
{
	// wstawiamy kilka parametrów do szablonu
	$this->template->param = $value;
	// i renderować go
	$this->template->render(__DIR__ . '/poll.latte');
}
```

Znacznik `{control}` umożliwia przekazanie parametrów do metody `render()`:

```latte
{control poll $id, $message}
```

```php .{file:PollControl.php}
public function render(int $id, string $message): void
{
	// ...
}
```

Czasami komponent może składać się z kilku części, które chcemy renderować osobno. Dla każdego z nich tworzymy własną metodę renderowania, tutaj w przykładzie dla przykładu `renderPaginator()`:

```php .{file:PollControl.php}
public function renderPaginator(): void
{
	// ...
}
```

A następnie wywołaj go w szablonie za pomocą:

```latte
{control poll:paginator}
```

Dla lepszego zrozumienia dobrze jest wiedzieć, jak przetłumaczyć ten tag na język PHP.

```latte
{control poll}
{control poll:paginator 123, 'hello'}
```

tłumaczy się jako:

```php
$control->getComponent('poll')->render();
$control->getComponent('poll')->renderPaginator(123, 'hello');
```

Metoda `getComponent()` zwraca komponent `poll` i wywołuje metodę `render()`, lub `renderPaginator()` nad tym komponentem, jeśli w znaczniku po dwukropku określono inną metodę renderowania.

.[caution]
Zauważ, że jeśli **`=>`** pojawia się gdziekolwiek w parametrach, wszystkie parametry zostaną zawinięte w tablicę i przekazane jako pierwszy argument:

```latte
{control poll, id: 123, message: 'hello'}
```

zostanie przetłumaczone jako:

```php
$control->getComponent('poll')->render(['id' => 123, 'message' => 'hello']);
```

Renderowanie podkomponentu:

```latte
{control cartControl-someForm}
```

tłumaczy się jako:

```php
$control->getComponent("cartControl-someForm")->render();
```

Komponenty, podobnie jak prezentery, przekazują automatycznie kilka przydatnych zmiennych do szablonów:

- `$basePath` to bezwzględna ścieżka URL do katalogu głównego (np. `/eshop`)
- `$baseUrl` to bezwzględny adres URL do katalogu głównego (np. `http://localhost/eshop`)
- `$user` jest obiektem [reprezentującym użytkownika |security:authentication]
- `$presenter` jest obecnym prezenterem
- `$control` to aktualny składnik
- `$flashes` jest tablicą [komunikatów |#Flash-Messages] wysyłanych przez funkcję `flashMessage()`


Sygnał .[#toc-signal]
=====================

Wiemy już, że nawigacja w aplikacji Nette polega na łączeniu lub przekierowaniu do par `Presenter:action`. Ale co jeśli chcemy wykonać akcję tylko na **bieżącej stronie**? Na przykład zmienić kolejność kolumn w tabeli; usunąć element; przełączyć tryb jasny/ciemny; przesłać formularz; głosować w ankiecie; itp.

Tego typu żądania nazywane są sygnałami. I tak jak akcje, wywołują one metody `action<Action>()` lub `render<Action>()`, sygnały wywołują metody `handle<Signal>()`. O ile pojęcie akcji (lub widoku) dotyczy wyłącznie prezenterów, o tyle sygnały odnoszą się do wszystkich komponentów. A zatem także prezenterów, gdyż `UI\Presenter` jest potomkiem `UI\Control`.

```php
public function handleClick(int $x, int $y): void
{
	// ... przetwarzanie sygnału ...
}
```

Link wywołujący sygnał tworzymy w zwykły sposób, czyli w szablonie za pomocą atrybutu `n:href` lub znacznika `{link}`, a w kodzie za pomocą metody `link()` Więcej informacji znajdziesz w rozdziale [Tworzenie linków URL |creating-links#Links-to-Signal].

```latte
<a n:href="click! $x, $y">click here</a>
```

Sygnał jest zawsze wywoływany na bieżącym prezenterze i widoku, więc nie można go wywołać na innym prezenterze lub widoku.

Tak więc sygnał powoduje przeładowanie strony dokładnie w taki sam sposób, jak oryginalne żądanie, ale wywołuje metodę obsługi sygnału z odpowiednimi parametrami. Jeśli metoda nie istnieje, rzucany jest wyjątek [api:Nette\Application\UI\BadSignalException], który jest wyświetlany użytkownikowi jako strona błędu 403 Forbidden.


Snippety i AJAX .[#toc-snippets-and-ajax]
=========================================

Snippety mogą przypominać nieco AJAX: handlery, które są wywoływane na bieżącej stronie. I masz rację, sygnały są rzeczywiście często wywoływane za pomocą AJAX-a, a następnie tylko zmienione części strony są przekazywane do przeglądarki. Albo tzw. snippety. Więcej informacji można znaleźć na [stronie poświęconej AJAX-owi |ajax].


Wiadomości błyskowe .[#toc-flash-messages]
==========================================

Komponent posiada własne, niezależne od prezentera repozytorium wiadomości flash. Są to komunikaty, które np. informują o wyniku operacji. Ważną cechą wiadomości flash jest to, że są one dostępne w szablonie nawet po przekierowaniu. Nawet po ich wyświetleniu pozostaną na żywo przez kolejne 30 sekund - na przykład w przypadku, gdy użytkownik odświeży stronę z powodu błędu transmisji - więc komunikat nie zniknie natychmiast.

Wysyłanie jest obsługiwane przez metodę [flashMessage |api:Nette\Application\UI\Control::flashMessage()]. Pierwszym parametrem jest tekst wiadomości lub obiekt `stdClass` reprezentujący wiadomość. Opcjonalnym drugim parametrem jest jego typ (błąd, ostrzeżenie, info, itd.). Metoda `flashMessage()` zwraca instancję wiadomości flash jako obiekt `stdClass`, do którego można dodać dodatkowe informacje.

```php
$this->flashMessage('Item has been deleted.');
$this->redirect(/* ... */); // i przekierować
```

Do szablonu wiadomości te są dostępne w zmiennej `$flashes` jako obiekty `stdClass`, które zawierają właściwości `message` (tekst wiadomości), `type` (typ wiadomości) i mogą zawierać wspomniane już informacje o użytkowniku. Na przykład wyrenderujmy je w następujący sposób:

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


Trwałe parametry .[#toc-persistent-parameters]
==============================================

Trwałe parametry są używane do utrzymania stanu w komponentach pomiędzy różnymi żądaniami. Ich wartość pozostaje taka sama nawet po kliknięciu linku. W przeciwieństwie do danych sesji, są one przekazywane w adresie URL. I są przekazywane automatycznie, łącznie z linkami utworzonymi w innych komponentach na tej samej stronie.

Na przykład, masz komponent stronicowania treści. Na stronie może być kilka takich komponentów. I chcesz, aby wszystkie komponenty pozostały na bieżącej stronie, gdy użytkownik kliknie na link. Dlatego czynimy numer strony (`page`) trwałym parametrem.

Tworzenie trwałych parametrów jest w Nette niezwykle proste. Wystarczy stworzyć właściwość publiczną i oznaczyć ją atrybutem: (poprzednio użyto `/** @persistent */` )

```php
use Nette\Application\Attributes\Persistent; // ta linia jest ważna

class PaginatingControl extends Control
{
	#[Persistent]
	public int $page = 1; // musi być publiczny
}
```

Zalecamy dołączenie typu danych (np. `int`) do właściwości, możesz także dołączyć wartość domyślną. Wartości parametrów mogą być [walidowane |#Validation of Persistent Parameters].

Możesz zmienić wartość trwałego parametru podczas tworzenia linku:

```latte
<a n:href="this page: $page + 1">next</a>
```

Można też go *resetować*, czyli usunąć z adresu URL. Przyjmie on wtedy swoją domyślną wartość:

```latte
<a n:href="this page: null">reset</a>
```


Trwałe komponenty .[#toc-persistent-components]
===============================================

Nie tylko parametry, ale także komponenty mogą być trwałe. Dla takiego komponentu, jego trwałe parametry są również przekazywane pomiędzy różnymi akcjami prezentera lub pomiędzy wieloma prezenterami. Oznaczamy trwałe komponenty poprzez adnotację klasy prezentera. Na przykład w ten sposób oznaczamy składniki `calendar` i `poll`:

```php
/**
 * @persistent(calendar, poll)
 */
class DefaultPresenter extends Nette\Application\UI\Presenter
{
}
```

Podkomponenty wewnątrz tych komponentów nie muszą być oznaczone, stają się również trwałe.

W PHP 8 możesz również używać atrybutów do oznaczania trwałych komponentów:

```php
use Nette\Application\Attributes\Persistent;

#[Persistent('calendar', 'poll')]
class DefaultPresenter extends Nette\Application\UI\Presenter
{
}
```


Komponenty z zależnościami .[#toc-components-with-dependencies]
===============================================================

Jak tworzyć komponenty z zależnościami, nie "brudząc" prezenterów, które będą z nich korzystać? Dzięki sprytnym funkcjom kontenera DI w Nette, podobnie jak w przypadku korzystania z tradycyjnych usług, możemy większość pracy pozostawić frameworkowi.

Weźmy jako przykład komponent, który ma zależność od serwisu `PollFacade`:

```php
class PollControl extends Control
{
	public function __construct(
		private int $id, // Id ankiety, za pomocą której można tworzyć komponenty
		private PollFacade $facade,
	) {
	}

	public function handleVote(int $voteId): void
	{
		$this->facade->vote($id, $voteId);
		// ...
	}
}
```

Gdybyśmy pisali klasyczny serwis, nie byłoby się czym przejmować. Kontener DI w niewidoczny sposób zająłby się przekazaniem wszystkich zależności. Ale zazwyczaj obsługujemy komponenty tworząc ich nową instancję bezpośrednio w prezenterze w [metodach fabrycznych |#Factory-Methods] `createComponent…()`. Ale przekazanie wszystkich zależności wszystkich komponentów do prezentera, aby następnie przekazać je do komponentów, jest uciążliwe. A ilość napisanego kodu...

Logicznym pytaniem jest, dlaczego po prostu nie zarejestrujemy komponentu jako klasycznej usługi, przekażemy go do prezentera, a następnie zwrócimy go w metodzie `createComponent…()`? Ale to podejście jest nieodpowiednie, ponieważ chcemy mieć możliwość wielokrotnego tworzenia komponentu.

Poprawnym rozwiązaniem jest napisanie fabryki komponentu, czyli klasy, która tworzy za nas komponent:

```php
class PollControlFactory
{
	public function __construct(
		private PollFacade $facade,
	) {
	}

	public function create(int $id): PollControl
	{
		return new PollControl($id, $this->facade);
	}
}
```

W ten sposób rejestrujemy fabrykę w naszym kontenerze w konfiguracji:

```neon
services:
	- PollControlFactory
```

i w końcu użyć go w naszym prezenterze:

```php
class PollPresenter extends Nette\Application\UI\Presenter
{
	public function __construct(
		private PollControlFactory $pollControlFactory,
	) {
	}

	protected function createComponentPollControl(): PollControl
	{
		$pollId = 1; // możemy przekazać nasz parametr
		return $this->pollControlFactory->create($pollId);
	}
}
```

Świetną rzeczą jest to, że Nette DI potrafi [generować |dependency-injection:factory] takie proste fabryki, więc zamiast pisać cały kod, wystarczy napisać jego interfejs:

```php
interface PollControlFactory
{
	public function create(int $id): PollControl;
}
```

I to jest właśnie to. Nette wewnętrznie implementuje ten interfejs i przekazuje go do prezentera, gdzie możemy go użyć. W magiczny sposób dodaje również do naszego komponentu parametr `$id` oraz instancję klasy `PollFacade`.


Komponenty w głębi .[#toc-advanced-use-of-components]
=====================================================

Komponenty w aplikacji Nette to części aplikacji internetowej wielokrotnego użytku, które osadzamy w stronach, co jest tematem tego rozdziału. Jakie dokładnie są możliwości takiego komponentu?

1) Jest renderowalny w szablonie
2) wie [, którą część siebie |ajax#snippets] renderować podczas żądania AJAX (snippets)
3) ma możliwość przechowywania swojego stanu w URL (trwałe parametry)
4) posiada zdolność do reagowania na działania (sygnały) użytkownika
5) tworzy strukturę hierarchiczną (gdzie korzeniem jest prezenter)

Każda z tych funkcji jest obsługiwana przez jedną z klas linii dziedziczenia. Renderingiem (1 + 2) zajmuje się [api:Nette\Application\UI\Control], włączaniem do [cyklu życia |presenters#life-cycle-of-presenter] (3, 4) klasa [api:Nette\Application\UI\Component], a tworzeniem struktury hierarchicznej (5) klasy [Container i Component |component-model:].

```
Nette\ComponentModel\Component  { IComponent }
|
+- Nette\ComponentModel\Container  { IContainer }
	|
	+- Nette\Application\UI\Component  { SignalReceiver, StatePersistent }
		|
		+- Nette\Application\UI\Control  { Renderable }
			|
			+- Nette\Application\UI\Presenter  { IPresenter }
```


Cykl życia komponentów .[#toc-zivotni-cyklus-componenty]
--------------------------------------------------------

[* lifecycle-component.svg *] *** *Cykl życia składników* .<>


Walidacja stałych parametrów .[#toc-validation-of-persistent-parameters]
------------------------------------------------------------------------

Wartości [trwałych parametrów |#persistent parameters] otrzymanych z adresów URL są zapisywane do właściwości przez metodę `loadState()`. Sprawdza ona również, czy typ danych określony dla właściwości pasuje, w przeciwnym razie odpowie błędem 404 i strona nie zostanie wyświetlona.

Nigdy ślepo nie ufaj trwałym parametrom, ponieważ mogą one zostać łatwo nadpisane przez użytkownika w adresie URL. Na przykład, w ten sposób sprawdzamy, czy numer strony `$this->page` jest większy niż 0. Dobrym sposobem na to jest nadpisanie metody `loadState()` wspomnianej powyżej:

```php
class PaginatingControl extends Control
{
	#[Persistent]
	public int $page = 1;

	public function loadState(array $params): void
	{
		parent::loadState($params); // tutaj jest ustawione $this->page
		// następuje sprawdzenie wartości użytkownika:
		if ($this->page < 1) {
			$this->error();
		}
	}
}
```

Procesem przeciwnym, czyli pobieraniem wartości z persistent properites, zajmuje się metoda `saveState()`.


Sygnały w głąb .[#toc-signaly-do-hloubky]
-----------------------------------------

Sygnał ten powoduje przeładowanie strony dokładnie tak samo jak oryginalne żądanie (z wyjątkiem wywołania przez AJAX) i wywołuje metodę `signalReceived($signal)`, której domyślna implementacja w klasie `Nette\Application\UI\Component` próbuje wywołać metodę składającą się ze słów `handle{signal}`. Dalsze przetwarzanie należy do obiektu. Obiekty dziedziczące po `Component` (czyli `Control` i `Presenter`) odpowiadają próbując wywołać metodę `handle{signal}` z odpowiednimi parametrami.

Innymi słowy, bierze definicję funkcji `handle{signal}` i wszystkie parametry, które przyszły z żądaniem, dołącza parametry z adresu URL do argumentów po nazwie i próbuje wywołać metodę. Na przykład wartość z parametru `id` w adresie URL jest przekazywana jako źródło `$id`, `something` z adresu URL jest przekazywany jako `$something` itd. A jeśli metoda nie istnieje, metoda `signalReceived` podnosi [wyjątek |api:Nette\Application\UI\BadSignalException].

Sygnał może odebrać każdy komponent, prezenter lub obiekt, który implementuje interfejs `SignalReceiver` i jest podłączony do drzewa komponentów.

Głównymi odbiorcami sygnałów będą `Presentery` oraz komponenty wizualne dziedziczące po `Control`. Sygnał ma służyć jako sygnał dla obiektu, że powinien coś zrobić - ankieta powinna zliczyć głos od użytkownika, blok wiadomości powinien się rozwinąć i wyświetlić dwa razy więcej wiadomości, formularz został przesłany i powinien przetworzyć dane, i tak dalej.

Tworzymy adres URL dla sygnału za pomocą metody [Component::link() |api:Nette\Application\UI\Component::link()]. Przekazujemy ciąg `{signal}!` jako parametr `$destination` oraz tablicę argumentów, które chcemy przekazać do sygnału jako `$args`. Sygnał jest zawsze wywoływany na bieżącym widoku z bieżącymi parametrami, parametry sygnału są po prostu dodawane. Dodatkowo na samym początku dodawany jest **parametr `?do`, który określa sygnał**.

Jego format to albo `{signal}`, albo `{signalReceiver}-{signal}`. `{signalReceiver}` to nazwa komponentu w prezenterze. Dlatego w nazwie komponentu nie może być myślnika - służy on do oddzielenia nazwy komponentu od sygnału, ale możliwe jest osadzenie w ten sposób kilku komponentów.

Metoda [isSignalReceiver() |api:Nette\Application\UI\Presenter::isSignalReceiver()] sprawdza, czy komponent (pierwszy argument) jest odbiornikiem sygnału (drugi argument). Drugi argument może być pominięty - wtedy sprawdza, czy dany komponent jest odbiornikiem jakiegokolwiek sygnału. Drugi parametr może być `true`, aby sprawdzić, czy nie tylko określony komponent jest odbiornikiem, ale także dowolny z jego potomków.

Na dowolnym etapie przed `handle{signal}` możemy wykonać sygnał ręcznie, wywołując metodę [processSignal() |api:Nette\Application\UI\Presenter::processSignal()], która zajmuje się obsługą sygnału - bierze komponent, który określił się jako odbiorca sygnału (jeśli nie określono odbiorcy sygnału, jest nim sam prezenter) i wysyła mu sygnał.

Przykład:

```php
if ($this->isSignalReceiver($this, 'paging') || $this->isSignalReceiver($this, 'sorting')) {
	$this->processSignal();
}
```

Oznacza to, że sygnał jest przedwcześnie wykonany i nie zostanie ponownie wywołany.