Presentery

Seznámíme se s tím, jak se v Nette píší presentery a šablony. Po přečtení budete vědět:

  • jak funguje presenter
  • co jsou persistentní parametry
  • jak se kreslí šablony

Už víme, že presenter je třída, která představuje nějakou konkrétní stránku webové aplikace, např. homepage; produkt v e-shopu; přihlašovací formulář; sitemap feed atd. Aplikace může mít od jednoho po tisíce presenterů. V jiných frameworcích se jim také říká controllery.

Obvykle se pod pojmem presenter myslí potomek třídy Nette\Application\UI\Presenter, který je vhodný pro generování webových rozhraní a kterému se budeme věnovat ve zbytku této kapitoly. V obecném smyslu je presenter jakýkoliv objekt implementující rozhraní Nette\Application\IPresenter.

Životní cyklus presenteru

Úkolem presenteru je vyřídit požadavek a vrátit odpověď (což může být HTML stránka, obrázek, přesměrování atd.).

Tedy na počátku je mu předán požadavek. Není to přímo HTTP požadavek, ale objekt Nette\Application\Request, do kterého byl HTTP požadavek přetransformován za pomoci routeru. S tímto objektem obvykle nepřijdeme do styku, neboť presenter zpracování požadavku chytře deleguje do dalších metod, které si teď ukážeme.

Životní cyklus presenteru

Obrázek představuje seznam metod, které se postupně od shora dolů volají, pokud existují. Žádná z nich existovat nemusí, můžeme mít úplně prázdný presenter bez jediné metody a postavit na něm jednoduchý statický web.

__construct()

Konstruktor nepatří tak úplně do životního cyklu presenteru, protože se volá v okamžiku vytváření objektu. Ale uvádíme jej kvůli důležitosti. Konstruktor (společně s metodou inject) slouží k předávání závislostí.

Presenter by neměl obstarávat byznys logiku aplikace, zapisovat a číst z databáze, provádět výpočty atd. Od toho jsou třídy z vrstvy, kterou označujeme jako model. Například třída ArticleRepository může mít na starosti načítání a ukládání článků. Aby s ní mohl presenter pracovat, nechá si ji předat pomocí dependency injection:

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

startup()

Ihned po obdržení požadavku se zavolá metoda startup(). Můžete ji využít k inicializaci properties, ověření uživatelských oprávnění atd. Je vyžadováno, aby metoda vždy volala předka parent::startup().

action<Action>(args...)

Obdoba metody render<View>(). Zatímco render<View>() je určená k tomu, aby připravila data pro konkrétní šablonu, která se následně vykreslí, tak v action<Action>() se zpracovává požadavek bez návaznosti na vykreslování šablony. Například se zpracují data, přihlásí či odhlásí uživatel, a tak podobně, a poté přesměruje jinam.

Důležité je, že action<Action>() se volá dříve než render<View>(), takže v ní můžeme případně změnit další běh dějin, tj. změnit šablonu, která se bude kreslit, a také metodu render<View>(), která se bude volat. A to pomocí setView('jineView').

Metodě se předávají parametry z požadavku. Je možné a doporučené uvést parametrům typy, např. actionShow(int $id, ?string $slug = null) – pokud bude parametr id chybět nebo pokud nebude integer, presenter vrátí chybu 404 a ukončí činnost.

handle<Signal>(args...)

Metoda zpracovává tzv. signály, se kterými se seznámíme v kapitole věnované komponentám. Je totiž určena zejména pro komponenty a zpracování AJAXových požadavků.

Metodě se předávají parametry z požadavku, jako v případě action<Action>(), včetně typové kontroly.

beforeRender()

Metoda beforeRender, jak už název napovídá, se volá před každou metodou render<View>(). Používá se pro společnou konfiguraci šablony, předání proměnných pro layout a podobně.

render<View>(args...)

Místo, kde připravujeme šablonu k následnému vykreslení, předáváme jí data atd.

Metodě se předávají parametry z požadavku, jako v případě action<Action>(), včetně typové kontroly.

public function renderShow(int $id): void
{
	// získáme data z modelu a předáme do šablony
	$this->template->article = $this->articles->getById($id);
}

afterRender()

Metoda afterRender, jak název opět napovídá, se volá za každou metodou render<View>(). Používá se spíš výjimečně.

shutdown()

Volá se na konci životního cyklu presenteru.

Dobrá rada, než půjdeme dál. Presenter jak vidno může obsluhovat více akcí/view, tedy mít více metod render<View>(). Ale doporučujeme navrhovat presentery s jednou nebo co nejméně akcemi.

Odeslání odpovědi

Odpovědí presenteru je zpravidla vykreslení šablony s HTML stránkou, ale může jí být také odeslání souboru, JSON nebo třeba přesměrování na jinou stránku.

Kdykoliv během životního cyklu můžeme některou z následujících metod odeslat odpověď a zároveň tak ukončit presenter:

Pokud žádnou z těchto metod nezavoláte, presenter automaticky přistoupí k vykreslí šablony. Proč? Protože v 99 % případů chceme vykreslit šablonu, tudíž presenter tohle chování bere jako výchozí a chce nám ulehčit práci.

Vytváření odkazů

Presenter disponuje metodou link(), pomocí které lze vytvářet URL odkazy na další presentery. Prvním parametrem je cílový presenter & akce, následují předávané argumenty, které mohou být uvedeny jako pole:

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

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

V šabloně se vytvářejí odkazy na další presentery & akce tímto způsobem:

<a n:href="Product:show $id">detail produktu</a>

Prostě místo reálného URL napíšete známý pár Presenter:action a uvedete případné parametry. Trik je v tom n:href, které říká, že tento atribut zpracuje Latte a vygeneruje reálné URL. V Nette tak vůbec nemusíte uvažovat nad URL, jen nad presentery a akcemi.

Více informací najdete v kapitole Vytváření odkazů URL.

Přesměrování

K přechodu na jiný presenter slouží metody redirect() a forward(), které mají velmi podobnou syntax jako metoda link().

Metoda forward() přejde na nový presenter okamžitě bez HTTP přesměrování:

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

Příklad tzv. dočasného přesměrování s HTTP kódem 302 (nebo 303, je-li metoda aktuálního požadavku POST):

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

Permanentní přesměrování s HTTP kódem 301 docílíte takto:

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

Na jinou URL mimo aplikaci lze přesměrovat metodou redirectUrl(). Jako druhý parametr lze uvést HTTP kód, výchozí je 302 (nebo 303, je-li metoda aktuálního požadavku POST):

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

Přesměrování okamžitě ukončí činnost presenteru vyhozením tzv. tiché ukončovací výjimky Nette\Application\AbortException.

Před přesměrováním lze odeslat flash message, tedy zprávy, které budou po přesměrování zobrazeny v šabloně.

Flash zprávy

Jde o zprávy obvykle informující o výsledku nějaké operace. Důležitým rysem flash zpráv je to, že jsou v šabloně k dispozici i po přesměrování. I po zobrazení zůstanou živé ještě dalších 30 sekund – například pro případ, že by z důvodu chybného přenosu uživatel dal stránku obnovit – zpráva mu tedy hned nezmizí.

Stačí zavolat metodu flashMessage() a o předání do šablony se postará presenter. Prvním parametrem je text zprávy a nepovinným druhým parametrem její typ (error, warning, info apod.). Metoda flashMessage() vrací instanci flash zprávy, které je možné přidávat další informace.

$this->flashMessage('Položka byla smazána.');
$this->redirect(/* ... */); // a přesměrujeme

Šabloně jsou tyto zprávy k dispozici v proměnné $flashes jako objekty stdClass, které obsahují vlastnosti message (text zprávy), type (typ zprávy) a mohou obsahovat již zmíněné uživatelské informace. Vykreslíme je třeba takto:

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

Chyba 404 a spol.

Pokud nelze splnit požadavek, třeba z důvodu, že článek který chceme zobrazit neexistuje v databázi, vyhodíme chybu 404 metodou error(?string $message = null, int $httpCode = 404).

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

HTTP kód chyby lze předat jako druhý parametr, výchozí je 404. Metoda funguje tak, že vyhodí výjimku Nette\Application\BadRequestException, načež Application předá řízení error-presenteru. Což je presenter, jehož úkolem je zobrazit stránku informující o nastalé chybě. Nastavení error-preseteru se provádí v konfiguraci application.

Odeslání JSON

Příklad action-metody, která odešle data ve formátu JSON a ukončí presenter:

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

Parametry požadavku

Presenter a také každá komponenta získává z HTTP požadavku své parametry. Jejich hodnotu zjistíte metodou getParameter($name) nebo getParameters(). Hodnoty jsou řetězce či pole řetězců, jde v podstatě o surové data získané přímo z URL.

Pro větší pohodlí doporučujeme parametry zpřístupnit přes property. Stačí je označit atributem #[Parameter]:

use Nette\Application\Attributes\Parameter;  // tento řádek je důležitý

class HomePresenter extends Nette\Application\UI\Presenter
{
	#[Parameter]
	public string $theme; // musí být public
}

U property doporučujeme uvádět i datový typ (např. string) a Nette podle něj hodnotu automaticky přetypuje. Hodnoty parametrů lze také validovat.

Při vytváření odkazu lze parametrům hodnotu přímo nastavit:

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

Persistentní parametry

Persistentní parametry slouží k udržování stavu mezi různými požadavky. Jejich hodnota zůstává stejná i po kliknutí na odkaz. Na rozdíl od dat v session se přenášejí v URL. A to zcela automaticky, není tedy potřeba je explicitně uvádět v link() nebo n:href.

Příklad použití? Máte multijazyčnou aplikaci. Aktuální jazyk je parameter, který musí být neustále součástí URL. Ale bylo by neskutečně únavné ho v každém odkazu uvádět. Tak z něj uděláte persistentní parametr lang a bude se přenášet sám. Paráda!

Vytvoření persistentního parametru je v Nette nesmírně jednoduché. Stačí vytvořit veřejnou property a označit ji atributem: (dříve se používalo /** @persistent */)

use Nette\Application\Attributes\Persistent;  // tento řádek je důležitý

class ProductPresenter extends Nette\Application\UI\Presenter
{
	#[Persistent]
	public string $lang; // musí být public
}

Pokud bude $this->lang mít hodnotu například 'en', tak i odkazy vytvořené pomocí link() nebo n:href budou obsahovat parameter lang=en. A po kliknutí na odkaz bude opět $this->lang = 'en'.

U property doporučujeme uvádět i datový typ (např. string) a můžete uvést i výchozí hodnotu. Hodnoty parametrů lze validovat.

Persistentní parametry se standardně přenášejí mezi všemi akcemi daného presenteru. Aby se přenášely i mezi více presentery, je potřeba je definovat buď:

  • ve společném předkovi, od kterého presentery dědí
  • v traitě, kterou presentery použijí:
trait LanguageAware
{
	#[Persistent]
	public string $lang;
}

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

Při vytváření odkazu lze persistentnímu parametru změnit hodnotu:

<a n:href="Product:show $id, lang: cs">detail v češtině</a>

Nebo jej lze vyresetovat, tj. odstranit z URL. Pak bude nabývat svou výchozí hodnotu:

<a n:href="Product:show $id, lang: null">klikni</a>

Interaktivní komponenty

Presentery v sobě mají zabudovaný komponentový systém. Komponenty jsou samostatné znovupoužitelné celky, které vkládáme do presenterů. Mohou to být formuláře, datagridy, menu, vlastně cokoliv, co má smysl používat opakovaně.

Jak se do presenteru komponenty vkládají a následně používají? To se dozvíte v kapitole Komponenty. Dokonce zjistíte, co mají společného s Hollywoodem.

A kde mohu získat komponenty? Na stránce Componette najdete open-source komponenty a také řadu dalších doplňku pro Nette, které sem umístili dobrovolníci z komunity okolo frameworku.

Jdeme do hloubky

S tím, co jsme si dosud v této kapitole ukázali, si nejspíš úplně vystačíte. Následující řádky jsou určeny těm, kdo se zajímají o presentery do hloubky a chtějí vědět úplně všechno.

Validace parametrů

Hodnoty parametrů požadavku a persistentních parametrů přijatých z URL zapisuje do properties metoda loadState(). Ta také kontroluje, zda odpovídá datový typ uvedený u property, jinak odpoví chybou 404 a stránka se nezobrazí.

Nikdy slepě nevěřte parametrům, protože mohou být snadno uživatelem přepsány v URL. Takto například ověříme, zda je jazyk $this->lang mezi podporovanými. Vhodnou cestou je přepsat zmíněnou metodu loadState():

class ProductPresenter extends Nette\Application\UI\Presenter
{
	#[Persistent]
	public string $lang;

	public function loadState(array $params): void
	{
		parent::loadState($params); // zde se nastaví $this->lang
		// následuje vlastní kontrola hodnoty:
		if (!in_array($this->lang, ['en', 'cs'])) {
			$this->error();
		}
	}
}

Uložení a obnovení požadavku

Požadavek, který vyřizuje presenter, je objekt Nette\Application\Request a vrací ho metoda presenteru getRequest().

Aktuální požadavek lze uložit do session nebo naopak z ní obnovit a nechat jej presenter znovu vykonat. To se hodí například v situaci, když uživatel vyplňuje formulář a vyprší mu přihlášení. Aby o data nepřišel, před přesměrováním na přihlašovací stránku aktuální požadavek uložíme do session pomocí $reqId = $this->storeRequest(), které vrátí jeho identifikátor v podobě krátkého řetězce a ten předáme jako parameter přihlašovacímu presenteru.

Po přihlášení zavoláme metodu $this->restoreRequest($reqId), která požadavek vyzvedne ze session a forwarduje na něj. Metoda přitom ověří, že požadavek vytvořil stejný uživatel, jako se nyní přihlásil. Pokud by se přihlásil jiný uživatel nebo klíč byl neplatný, neudělá nic a program pokračuje dál.

Podívejte se na návod Jak se vrátit k dřívější stránce.

Kanonizace

Presentery mají jednu opravdu skvělou vlastnost, která přispívá k lepšímu SEO (optimalizaci nalezitelnosti na internetu). Automaticky zabraňují existenci duplicitního obsahu na různých URL. Pokud k určitému cíli vede více URL adres, např. /index a /index?page=1, framework určí jednu z nich za primární (kanonickou) a ostatní na ni přesměruje pomocí HTTP kódu 301. Díky tomu vám vyhledávače stránky neindexují dvakrát a nerozmělní jejich page rank.

Tomuto procesu se říká kanonizace. Kanonickou URL je ta, kterou vygeneruje router, zpravidla tedy první odpovídající routa v kolekci.

Kanonizace je ve výchozím nastavení zapnutá a lze ji vypnout přes $this->autoCanonicalize = false.

K přesměrování nedojde při AJAXovém nebo POST požadavku, protože by došlo ke ztrátě dat nebo by to nemělo přidanou hodnotu z hlediska SEO.

Kanonizaci můžete vyvolat i manuálně pomocí metody canonicalize(), které se podobně jako metodě link() předá presenter, akce a parametry. Vyrobí odkaz a porovná ho s aktuální URL adresou. Pokud se liší, tak přesměruje na vygenerovaný odkaz.

public function actionShow(int $id, ?string $slug = null): void
{
	$realSlug = $this->facade->getSlugForId($id);
	// přesměruje, pokud $slug se liší od $realSlug
	$this->canonicalize('Product:show', [$id, $realSlug]);
}

Události

Kromě metod startup(), beforeRender() a shutdown(), které se volají jako součást životního cyklu presenteru, lze definovat ještě další funkce, které se mají automaticky zavolat. Presenter definuje tzv. událost, jejichž handlery přidáte do polí $onStartup, $onRender a $onShutdown.

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

Handlery v poli $onStartup se volají těsně před metodou startup(), dále $onRender mezi beforeRender() a render<View>() a nakonec $onShutdown těsně před shutdown().

Odpovědi

Odpověď, kterou vrací presenter, je objekt implementující rozhraní Nette\Application\Response. K dispozici je řada připravených odpovědí:

Odpovědi se odesílají metodou sendResponse():

use Nette\Application\Responses;

// Prostý text
$this->sendResponse(new Responses\TextResponse('Hello Nette!'));

// Odešle soubor
$this->sendResponse(new Responses\FileResponse(__DIR__ . '/invoice.pdf', 'Invoice13.pdf'));

// Odpovědí bude callback
$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));

Omezení přístupu pomocí #[Requires]

Atribut #[Requires] poskytuje pokročilé možnosti pro omezení přístupu k presenterům a jejich metodám. Lze jej použít pro specifikaci HTTP metod, vyžadování AJAXového požadavku, omezení na stejný původ (same origin), a přístup pouze přes forwardování. Atribut lze aplikovat jak na třídy presenterů, tak na jednotlivé metody action<Action>(), render<View>(), handle<Signal>() a createComponent<Name>().

Můžete určit tyto omezení:

  • na HTTP metody: #[Requires(methods: ['GET', 'POST'])]
  • vyžadování AJAXového požadavku: #[Requires(ajax: true)]
  • přístup pouze ze stejného původu: #[Requires(sameOrigin: true)]
  • přístup pouze přes forward: #[Requires(forward: true)]
  • omezení na konkrétní akce: #[Requires(actions: 'default')]

Podrobnosti najdete v návodu Jak používat atribut Requires.

Kontrola HTTP metody

Presentery v Nette automaticky ověřují HTTP metodu každého příchozího požadavku. Důvodem pro tuto kontrolu je především bezpečnost. Standardně jsou povoleny metody GET, POST, HEAD, PUT, DELETE, PATCH.

Chcete-li povolit navíc například metodu OPTIONS, použijte k tomu atribut #[Requires] (od Nette Application v3.2):

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

Ve verzi 3.1 se ověření provádí v checkHttpMethod(), která zjišťuje, zda je metoda specifikovaná v požadavku obsažena v poli $presenter->allowedMethods. Přidání metody udělejte takto:

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

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.

Další četba

  1. Dokumentace
  2. Nette Application
  3. Presentery
verze: 4.0 3.x 2.x