Interaktivne komponente
***********************

<div class=perex>

Komponente so ločeni predmeti za večkratno uporabo, ki jih namestimo na strani. To so lahko obrazci, podatkovne mreže, ankete, pravzaprav vse, kar je smiselno uporabljati večkrat. Prikazali bomo:

- kako uporabljati komponente?
- kako jih napisati?
- kaj so signali?

</div>

Nette ima vgrajen sistem komponent. Starejši med vami se morda spomnite nečesa podobnega iz Delphija ali ASP.NET Web Forms. React ali Vue.js sta zgrajena na nečem zelo podobnem. Vendar pa je v svetu ogrodij PHP to povsem edinstvena lastnost.

Hkrati pa komponente temeljito spremenijo pristop k razvoju aplikacij. Strani lahko sestavite iz vnaprej pripravljenih enot. Ali v administraciji potrebujete podatkovno mrežo? Najdete jo lahko v [Componette |https://componette.org/search/component], skladišču odprtokodnih dodatkov (ne le komponent) za Nette, in jo preprosto prilepite v predstavnik.

V predstavitveni program lahko vključite poljubno število komponent. V nekatere komponente pa lahko vstavite druge komponente. Tako nastane drevo komponent, katerega koren je predstavnik.


Tovarniške metode .[#toc-factory-methods]
=========================================

Kako se komponente namestijo in nato uporabijo v predstavitvenem programu? Običajno z uporabo tovarniških metod.

Tovarna komponent je eleganten način za ustvarjanje komponent samo takrat, ko jih resnično potrebujemo (lenoba / na zahtevo). Celotna čarovnija je v izvajanju metode, imenovane `createComponent<Name>()`, kjer `<Name>` je ime komponente, ki se ustvari in vrne.

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

Ker so vse komponente ustvarjene v ločenih metodah, je koda čistejša in lažje berljiva.

.[note]
Imena komponent se vedno začnejo z malo črko, čeprav so v imenu metode zapisana z veliko začetnico.

Nikoli ne kličemo tovarn neposredno, pokličejo se samodejno, ko prvič uporabimo komponente. Zaradi tega se komponenta ustvari v pravem trenutku in le, če jo resnično potrebujemo. Če komponente ne bi uporabili (na primer pri kakšni zahtevi AJAX, kjer vrnemo le del strani, ali ko so deli v predpomnilniku), se sploh ne bi ustvarila in prihranili bi zmogljivost strežnika.

```php .{file:DefaultPresenter.php}
// dostopamo do komponente in ali je bilo to prvič,
// pokliče createComponentPoll(), da jo ustvari
$poll = $this->getComponent('poll');
// alternativna sintaksa: $poll = $this['poll'];
```

V predlogi lahko komponento prikažete z uporabo oznake [{control} |#Rendering]. Tako ni potrebe po ročnem posredovanju komponent predlogi.

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

{control poll}
```


Hollywoodski slog .[#toc-hollywood-style]
=========================================

Sestavni deli pogosto uporabljajo kul tehniko, ki jo radi imenujemo hollywoodski slog. Zagotovo poznate kliše, ki ga igralci pogosto slišijo na kastingih: "Ne kličite nas, mi bomo poklicali vas." In prav za to gre v tem primeru.

V Nette, namesto da bi nenehno postavljali vprašanja ("je bil obrazec oddan?", "je bil veljaven?" ali "je kdo pritisnil ta gumb?"), ogrodju poveste "ko se to zgodi, pokliči to metodo" in mu prepustite nadaljnje delo. Če programirate v jeziku JavaScript, ste seznanjeni s tem slogom programiranja. Napišete funkcije, ki se pokličejo, ko se zgodi določen dogodek. In gonilo jim posreduje ustrezne parametre.

To popolnoma spremeni način pisanja aplikacij. Več nalog, kot jih lahko prenesete na ogrodje, manj dela imate. In manj lahko pozabite.


Kako napisati komponento .[#toc-how-to-write-a-component]
=========================================================

S komponento običajno mislimo na potomce razreda [api:Nette\Application\UI\Control]. Tudi sam predstavnik [api:Nette\Application\UI\Presenter] je potomec razreda `Control`.

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

class PollControl extends Control
{
}
```


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

Vemo že, da se oznaka `{control componentName}` uporablja za risanje komponente. Pravzaprav kliče metodo `render()` komponente, v kateri poskrbimo za upodabljanje. Podobno kot v predstavitvenem programu imamo tudi tu v spremenljivki `$this->template` [predlogo Latte |templates], ki ji posredujemo parametre. Za razliko od uporabe v predstavitvenem programu moramo določiti datoteko predloge in ji omogočiti, da se izrisuje:

```php .{file:PollControl.php}
public function render(): void
{
	// v predlogo bomo vnesli nekaj parametrov
	$this->template->param = $value;
	// in jo narisali
	$this->template->render(__DIR__ . '/poll.latte');
}
```

Z oznako `{control}` lahko metodi `render()` posredujemo parametre:

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

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

Včasih je lahko komponenta sestavljena iz več delov, ki jih želimo prikazati ločeno. Za vsakega od njih bomo ustvarili svojo metodo upodabljanja, tu je na primer `renderPaginator()`:

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

V predlogi jo nato pokličemo z uporabo:

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

Za boljše razumevanje je dobro vedeti, kako je oznaka sestavljena v kodo PHP.

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

To se sestavi v:

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

`getComponent()` metoda vrne komponento `poll`, nato pa se na njej kliče metoda `render()` oziroma `renderPaginator()`.

.[caution]
Če se kjer koli v delu parametrov uporabi **`=>`**, se vsi parametri zavijejo v polje in posredujejo kot prvi argument:

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

se pretvori v:

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



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

sestavi na:

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

Komponente, kot so predstavniki, predlogam samodejno posredujejo več uporabnih spremenljivk:

- `$basePath` je absolutna pot URL do korenskega dirja (na primer `/CD-collection`)
- `$baseUrl` je absolutna pot URL do korenskega dirja (na primer `http://localhost/CD-collection`)
- `$user` je objekt, ki [predstavlja uporabnika |security:authentication]
- `$presenter` je trenutni predstavnik
- `$control` je trenutna komponenta
- `$flashes` seznam [sporočil, |#flash-messages] poslanih z metodo `flashMessage()`


Signal .[#toc-signal]
=====================

Vemo že, da je navigacija v aplikaciji Nette sestavljena iz povezovanja ali preusmerjanja na pare `Presenter:action`. Kaj pa, če želimo izvesti dejanje samo na **tekoči strani**? Na primer, spremeniti vrstni red razvrščanja stolpca v tabeli; izbrisati element; preklopiti svetlobni/temni način; oddati obrazec; glasovati v anketi; itd.

Tovrstna zahteva se imenuje signal. In tako kot akcije kličejo metode `action<Action>()` ali `render<Action>()`, signali kličejo metode `handle<Signal>()`. Medtem ko se koncept akcije (ali pogleda) nanaša samo na predstavnike, signali veljajo za vse komponente. Torej tudi za predstavnike, saj je `UI\Presenter` potomec `UI\Control`.

```php
public function handleClick(int $x, int $y): void
{
	// ... obdelava signalov ...
}
```

Povezava, ki kliče signal, se ustvari na običajen način, tj. v predlogi z atributom `n:href` ali oznako `{link}`, v kodi pa z metodo `link()`. Več v poglavju [Ustvarjanje povezav URL |creating-links#Links to Signal].

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

Signal se vedno pokliče v trenutnem predstavniku in pogledu, zato povezave do signala ni mogoče vzpostaviti v drugem predstavniku/ukrepu.

Tako signal povzroči ponovno nalaganje strani na popolnoma enak način kot v prvotni zahtevi, le da dodatno pokliče metodo za obdelavo signala z ustreznimi parametri. Če metoda ne obstaja, se vrže izjema [api:Nette\Application\UI\BadSignalException], ki se uporabniku prikaže kot stran z napako 403 Forbidden.


Utrinki in AJAX .[#toc-snippets-and-ajax]
=========================================

Signali vas morda malce spominjajo na AJAX: obdelave, ki se kličejo na trenutni strani. In prav imate, signale res pogosto kličemo z uporabo AJAX-a, nato pa brskalniku posredujemo le spremenjene dele strani. Imenujejo se odlomki (snippets). Več informacij lahko najdete na [strani o AJAXu |ajax].


Sporočila Flash .[#toc-flash-messages]
======================================

Komponenta ima lastno shrambo sporočil flash, ki je neodvisna od predstavnika. To so sporočila, ki na primer obveščajo o rezultatu operacije. Pomembna lastnost bliskovnih sporočil je, da so na voljo v predlogi tudi po preusmeritvi. Tudi po prikazu bodo ostala živa še 30 sekund - na primer, če bi uporabnik nenamerno osvežil stran - sporočilo se ne bo izgubilo.

Pošiljanje se izvede z metodo [flashMessage |api:Nette\Application\UI\Control::flashMessage()]. Prvi parameter je besedilo sporočila ali objekt `stdClass`, ki predstavlja sporočilo. Neobvezni drugi parameter je njegova vrsta (napaka, opozorilo, informacija itd.). Metoda `flashMessage()` vrne primerek sporočila flash kot objekt stdClass, ki mu lahko posredujete informacije.

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

V predlogi so ta sporočila na voljo v spremenljivki `$flashes` kot objekti `stdClass`, ki vsebujejo lastnosti `message` (besedilo sporočila), `type` (vrsta sporočila) in lahko vsebujejo že omenjene podatke o uporabniku. Narišemo jih na naslednji način:

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


Trajni parametri .[#toc-persistent-parameters]
==============================================

Trajni parametri se uporabljajo za ohranjanje stanja v komponentah med različnimi zahtevami. Njihova vrednost ostane enaka tudi po kliku na povezavo. Za razliko od podatkov seje se prenesejo v naslovu URL. In se prenesejo samodejno, vključno s povezavami, ustvarjenimi v drugih komponentah na isti strani.

Na primer, imate komponento za listanje vsebine. Na strani je lahko več takšnih komponent. Želite, da vse komponente ostanejo na trenutni strani, ko kliknete povezavo. Zato je številka strani (`page`) trajni parameter.

Ustvarjanje trajnega parametra je v programu Nette zelo enostavno. Ustvarite le javno lastnost in jo označite z atributom: (prej je bila uporabljena `/** @persistent */` )

```php
use Nette\Application\Attributes\Persistent; // ta vrstica je pomembna

class PaginatingControl extends Control
{
	#[Persistent]
	public int $page = 1; // morajo biti javni.
}
```

Priporočamo, da pri lastnosti navedete podatkovno vrsto (npr. `int`), vključite pa lahko tudi privzeto vrednost. Vrednosti parametrov je mogoče [potrditi |#Validation of Persistent Parameters].

Pri ustvarjanju povezave lahko spremenite vrednost trajnega parametra:

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

Lahko ga tudi *resetirate*, tj. odstranite iz URL-ja. Nato bo prevzel privzeto vrednost:

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


Trajne komponente .[#toc-persistent-components]
===============================================

Ne le parametri, tudi komponente so lahko trajne. Njihovi trajni parametri se prenašajo tudi med različnimi akcijami ali med različnimi predstavniki. Trajne komponente označimo s temi opombami za razred presenter. Na primer, tukaj komponente `calendar` in `poll` označimo na naslednji način:

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

Podsestav ni treba označiti kot trajne, saj so trajne samodejno.

V PHP 8 lahko za označevanje trajnih komponent uporabite tudi atribute:

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

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


Komponente z odvisnostmi .[#toc-components-with-dependencies]
=============================================================

Kako ustvariti komponente z odvisnostmi, ne da bi "zmotili" predstavnike, ki jih bodo uporabljali? Zahvaljujoč pametnim funkcijam vsebnika DI v Nette, lahko tako kot pri uporabi tradicionalnih storitev večino dela prepustimo ogrodju.

Kot primer vzemimo komponento, ki je odvisna od storitve `PollFacade`:

```php
class PollControl extends Control
{
	public function __construct(
		private int $id, // Id ankete, za katero je ustvarjena komponenta
		private PollFacade $facade,
	) {
	}

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

Če bi pisali klasično storitev, nam ne bi bilo treba skrbeti. Kontejner DI bi nevidno poskrbel za posredovanje vseh odvisnosti. Vendar pa komponente običajno obravnavamo tako, da ustvarimo njihov nov primerek neposredno v predstavniku v [tovarniških metodah |#factory methods] `createComponent...()`. Toda posredovanje vseh odvisnosti vseh komponent predstavniku, da bi jih nato posredoval komponentam, je okorno. In količina kode, ki je napisana...

Logično vprašanje je, zakaj ne bi komponente preprosto registrirali kot klasično storitev, jo posredovali predstavniku in jo nato vrnili v metodi `createComponent...()`? Toda ta pristop je neprimeren, saj želimo imeti možnost, da komponento ustvarimo večkrat.

Pravilna rešitev je, da za komponento napišemo tovarno, tj. razred, ki za nas ustvari komponento:

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

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

Zdaj našo storitev registriramo v vsebniku DI za konfiguracijo:

```neon
services:
	- PollControlFactory
```

Na koncu bomo to tovarno uporabili v našem predstavitvenem programu:

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

	protected function createComponentPollControl(): PollControl
	{
		$pollId = 1; // lahko posredujemo naš parameter
		return $this->pollControlFactory->create($pollId);
	}
}
```

Odlično je, da lahko Nette DI [ustvari |dependency-injection:factory] tako preproste tovarne, tako da morate namesto celotne kode napisati le njen vmesnik:

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

To je vse. Nette interno implementira ta vmesnik in ga vbrizga v naš predstavnik, kjer ga lahko uporabimo. Prav tako čudežno posreduje naš parameter `$id` in primerek razreda `PollFacade` v našo komponento.


Komponente poglobljeno .[#toc-components-in-depth]
==================================================

Komponente v aplikaciji Nette so ponovno uporabni deli spletne aplikacije, ki jih vgrajujemo v strani, kar je predmet tega poglavja. Kakšne natančno so zmožnosti takšne komponente?

1) mogoče jo je izrisati v predlogi
2) ve, [kateri del sebe |ajax#snippets] naj prikaže med zahtevo AJAX (fragmenti).
3) ima možnost shranjevanja svojega stanja v naslovu URL (trajni parametri).
4) ima sposobnost odzivanja na dejanja uporabnika (signali)
5) ustvarja hierarhično strukturo (kjer je korenski element predstavnik)

Za vsako od teh funkcij skrbi eden od razredov dedne linije. Za upodabljanje (1 + 2) skrbi razred [api:Nette\Application\UI\Control], za vključitev v [življenjski cikel |presenters#life-cycle-of-presenter] (3, 4) razred [api:Nette\Application\UI\Component], za ustvarjanje hierarhične strukture (5) pa razreda [Container in 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 }
```


Življenjski cikel komponente .[#toc-life-cycle-of-component]
------------------------------------------------------------

[* lifecycle-component.svg *] *** *Življenjski cikel komponente* .<>


Potrjevanje trajnih parametrov .[#toc-validation-of-persistent-parameters]
--------------------------------------------------------------------------

Vrednosti [trajnih parametrov |#persistent parameters], prejetih z naslovov URL, se zapišejo v lastnosti z metodo `loadState()`. Preveri tudi, ali se podatkovna vrsta, določena za lastnost, ujema, sicer se odzove z napako 404 in stran se ne prikaže.

Nikoli ne zaupajte slepo trajnim parametrom, saj jih lahko uporabnik zlahka prepiše v naslovu URL. Tako na primer preverimo, ali je številka strani `$this->page` večja od 0. Dober način za to je, da prekrijemo zgoraj omenjeno metodo `loadState()`:

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

	public function loadState(array $params): void
	{
		parent::loadState($params); // tukaj je nastavljen $this->page
		// sledi preverjanju uporabniške vrednosti:
		if ($this->page < 1) {
			$this->error();
		}
	}
}
```

Nasprotni postopek, to je zbiranje vrednosti iz trajnih lastnosti, je obdelan z metodo `saveState()`.


Signali v globino .[#toc-signals-in-depth]
------------------------------------------

Signal povzroči ponovno nalaganje strani kot prvotna zahteva (z izjemo AJAX) in kliče metodo `signalReceived($signal)`, katere privzeta implementacija v razredu `Nette\Application\UI\Component` poskuša poklicati metodo, sestavljeno iz besed `handle{Signal}`. Nadaljnja obdelava je odvisna od danega predmeta. Objekti, ki so potomci `Component` (tj. `Control` in `Presenter`), poskušajo poklicati `handle{Signal}` z ustreznimi parametri.

Z drugimi besedami: vzame se definicija metode `handle{Signal}` in vsi parametri, ki so bili prejeti v zahtevi, se ujemajo s parametri metode. To pomeni, da se parameter `id` iz naslova URL ujema s parametrom metode `$id`, `something` s parametrom `$something` in tako naprej. In če metoda ne obstaja, metoda `signalReceived` vrže [izjemo |api:Nette\Application\UI\BadSignalException].

Signal lahko prejme vsaka komponenta, predstavnik objekta, ki implementira vmesnik `SignalReceiver`, če je povezan z drevesom komponent.

Glavni prejemniki signalov so `Presenters` in vizualne komponente, ki razširjajo `Control`. Signal je znak za objekt, da mora nekaj storiti - anketa šteje glas uporabnika, polje z novicami se mora razviti, obrazec je bil poslan in mora obdelati podatke itd.

URL za signal se ustvari z metodo [Component::link() |api:Nette\Application\UI\Component::link()]. Kot parameter `$destination` posredujemo niz `{signal}!`, kot `$args` pa polje argumentov, ki jih želimo posredovati izvajalcu signala. Parametri signala so priključeni na naslov URL trenutnega predstavnika/ogleda. **Parameter `?do` v naslovu URL določa klicani signal.**

Njegova oblika je `{signal}` ali `{signalReceiver}-{signal}`. `{signalReceiver}` je ime komponente v predstavniku. Zato pomišljaj (nenatančno pomišljaj) ne sme biti prisoten v imenu komponent - uporablja se za razdelitev imena komponente in signala, vendar je mogoče sestaviti več komponent.

Metoda [isSignalReceiver() |api:Nette\Application\UI\Presenter::isSignalReceiver()] preveri, ali je komponenta (prvi argument) sprejemnik signala (drugi argument). Drugi argument lahko izpustite - takrat ugotovi, ali je komponenta sprejemnik katerega koli signala. Če je drugi parameter `true`, preveri, ali je komponenta ali njeni potomci sprejemniki signala.

V kateri koli fazi pred `handle{Signal}` se lahko signal izvede ročno s klicem metode [processSignal() |api:Nette\Application\UI\Presenter::processSignal()], ki prevzame odgovornost za izvedbo signala. Vzame komponento prejemnika (če ni nastavljena, je to sam predvajalnik) in ji pošlje signal.

Primer:

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

Signal se izvede predčasno in ne bo več poklican.