Presentatori
************

<div class=perex>

Impareremo a scrivere presentatori e modelli in Nette. Dopo la lettura saprete che:

- come funziona il presentatore
- cosa sono i parametri persistenti
- come rendere un modello

</div>

[Sappiamo già |how-it-works#nette-application] che un presenter è una classe che rappresenta una pagina specifica di un'applicazione web, come ad esempio una homepage, un prodotto in un e-shop, un modulo di iscrizione, un feed sitemap, ecc. L'applicazione può avere da uno a migliaia di presenter. In altri framework, sono noti anche come controllori.

Di solito, il termine presenter si riferisce a un discendente della classe [api:Nette\Application\UI\Presenter], adatta alle interfacce web e di cui parleremo nel resto del capitolo. In senso generale, un presentatore è un qualsiasi oggetto che implementa l'interfaccia [api:Nette\Application\IPresenter].


Ciclo di vita del presentatore .[#toc-life-cycle-of-presenter]
==============================================================

Il compito del presentatore è quello di elaborare la richiesta e restituire una risposta (che può essere una pagina HTML, un'immagine, un reindirizzamento, ecc.)

All'inizio c'è una richiesta. Non si tratta direttamente di una richiesta HTTP, ma di un oggetto [api:Nette\Application\Request] in cui la richiesta HTTP è stata trasformata tramite un router. Di solito non entriamo in contatto con questo oggetto, perché il presentatore delega abilmente l'elaborazione della richiesta a metodi speciali, che vedremo ora.

[* lifecycle.svg *] *** *Ciclo di vita del presentatore* .<>

La figura mostra un elenco di metodi che vengono chiamati in sequenza dall'alto verso il basso, se esistono. Non è necessario che esistano, possiamo avere un presenter completamente vuoto, senza un solo metodo, e costruirci sopra un semplice web statico.


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

Il costruttore non appartiene esattamente al ciclo di vita del presentatore, perché viene chiamato al momento della creazione dell'oggetto. Ma lo citiamo per la sua importanza. Il costruttore (insieme al [metodo inject |best-practices:inject-method-attribute]) è usato per passare le dipendenze.

Il costruttore non deve occuparsi della logica di business dell'applicazione, scrivere e leggere dal database, eseguire calcoli, ecc. Questo è il compito delle classi di un livello, che chiamiamo modello. Per esempio, la classe `ArticleRepository` può essere responsabile del caricamento e del salvataggio degli articoli. Affinché il presentatore possa utilizzarla, viene [passata utilizzando la dependency injection |dependency-injection:passing-dependencies]:


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


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

Subito dopo la ricezione della richiesta, viene invocato il metodo `startup ()`. Si può usare per inizializzare le proprietà, controllare i privilegi dell'utente, ecc. È necessario chiamare sempre l'antenato `parent::startup()`.


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

Simile al metodo `render<View>()`. Mentre `render<View>()` è destinato a preparare i dati per un modello specifico, che viene successivamente reso, in `action<Action>()` una richiesta viene elaborata senza una successiva resa del template. Ad esempio, i dati vengono elaborati, l'utente viene connesso o disconnesso e così via e poi viene [reindirizzato altrove |#Redirection].

È importante che `action<Action>()` sia chiamato prima di `render<View>()`quindi al suo interno si può eventualmente modificare il corso successivo del ciclo di vita, cioè cambiare il template che sarà reso e anche il metodo `render<View>()` che sarà chiamato, utilizzando `setView('otherView')`.

I parametri della richiesta vengono passati al metodo. È possibile e consigliabile specificare i tipi di parametri, ad esempio `actionShow(int $id, ?string $slug = null)` - se il parametro `id` manca o non è un intero, il presentatore restituisce l'[errore 404 |#Error 404 etc.] e termina l'operazione.


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

Questo metodo elabora i cosiddetti segnali, di cui si parlerà nel capitolo sui [componenti |components#Signal]. È destinato principalmente ai componenti e all'elaborazione di richieste AJAX.

I parametri vengono passati al metodo, come nel caso di `action<Action>()`, compreso il controllo del tipo.


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

Il metodo `beforeRender`, come suggerisce il nome, viene chiamato prima di ogni metodo `render<View>()`. È usato per la configurazione comune dei template, per passare le variabili per il layout e così via.


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

Il luogo in cui si prepara il modello per il rendering successivo, si passano i dati ad esso, ecc.

I parametri vengono passati al metodo, come nel caso di `action<Action>()`, compreso il controllo del tipo.

```php
public function renderShow(int $id): void
{
	// otteniamo i dati dal modello e li passiamo al template
	$this->template->article = $this->articles->getById($id);
}
```


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

Il metodo `afterRender`, come suggerisce il nome, viene richiamato dopo ogni metodo. `render<View>()` metodo. Viene utilizzato piuttosto raramente.


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

Viene richiamato alla fine del ciclo di vita del presentatore.


**Buon consiglio prima di andare avanti**. Come si può vedere, il presentatore può gestire più azioni/visualizzazioni, cioè avere più metodi `render<View>()`. Ma si consiglia di progettare presentatori con una sola o il minor numero possibile di azioni.


Invio di una risposta .[#toc-sending-a-response]
================================================

La risposta del presentatore è solitamente il [rendering del template con la pagina HTML |templates], ma può anche essere l'invio di un file, di JSON o persino il reindirizzamento a un'altra pagina.

In qualsiasi momento del ciclo di vita, è possibile utilizzare uno dei seguenti metodi per inviare una risposta e allo stesso tempo uscire dal presentatore:

- `redirect()`, `redirectPermanent()`, `redirectUrl()` e `forward()` [reindirizzamenti |#Redirection]
- `error()` chiude il presentatore [per errore |#Error 404 etc.]
- `sendJson($data)` esce dal presentatore e [invia i dati |#Sending JSON] in formato JSON
- `sendTemplate()` abbandona il presentatore e [renderizza |templates]immediatamente [il template |templates]
- `sendResponse($response)` abbandona il presentatore e invia la [propria risposta |#Responses]
- `terminate()` abbandona il presentatore senza risposta

Se non si chiama nessuno di questi metodi, il presentatore procederà automaticamente al rendering del modello. Perché? Perché nel 99% dei casi si vuole disegnare un modello, quindi il presentatore assume questo comportamento come predefinito e vuole semplificarci il lavoro.


Creazione di collegamenti .[#toc-creating-links]
================================================

Il presentatore ha un metodo `link()`, utilizzato per creare collegamenti URL ad altri presentatori. Il primo parametro è il presentatore e l'azione di destinazione, seguito dagli argomenti, che possono essere passati come array:

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

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

Nel modello creiamo collegamenti ad altri presentatori e azioni come segue:

```latte
<a n:href="Product:show $id">product detail</a>
```

È sufficiente scrivere la nota coppia `Presenter:action` al posto dell'URL reale e includere eventuali parametri. Il trucco è `n:href`, che dice che questo attributo sarà elaborato da Latte e genererà un vero URL. In Nette non è necessario pensare agli URL, ma solo ai presentatori e alle azioni.

Per ulteriori informazioni, vedere [Creazione di collegamenti |Creating Links].


Reindirizzamento .[#toc-redirection]
====================================

Per passare a un altro presentatore si usano i metodi `redirect()` e `forward()`, che hanno una sintassi molto simile a quella del metodo [link() |#Creating Links].

Il metodo `forward()` passa immediatamente al nuovo presentatore senza reindirizzamento HTTP:

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

Esempio di un cosiddetto reindirizzamento temporaneo con codice HTTP 302 (o 303, se il metodo di richiesta corrente è POST):

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

Per ottenere un reindirizzamento permanente con codice HTTP 301 utilizzare:

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

È possibile reindirizzare a un altro URL al di fuori dell'applicazione utilizzando il metodo `redirectUrl()`. Il codice HTTP può essere specificato come secondo parametro; il valore predefinito è 302 (o 303, se il metodo di richiesta corrente è POST):

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

Il reindirizzamento termina immediatamente il ciclo di vita del presentatore lanciando la cosiddetta eccezione di terminazione silenziosa `Nette\Application\AbortException`.

Prima del reindirizzamento, è possibile inviare un [messaggio flash |#Flash Messages], che verrà visualizzato nel modello dopo il reindirizzamento.


Messaggi flash .[#toc-flash-messages]
=====================================

Sono messaggi che di solito informano sul risultato di un'operazione. Una caratteristica importante dei messaggi flash è che sono disponibili nel modello anche dopo il reindirizzamento. Anche dopo essere stati visualizzati, rimarranno in vita per altri 30 secondi - ad esempio, nel caso in cui l'utente dovesse involontariamente aggiornare la pagina - il messaggio non andrà perso.

Basta chiamare il metodo [flashMessage() |api:Nette\Application\UI\Control::flashMessage()] e il presentatore si occuperà di passare il messaggio al modello. Il primo parametro è il testo del messaggio e il secondo parametro opzionale è il suo tipo (errore, avviso, info ecc.). Il metodo `flashMessage()` restituisce un'istanza di messaggio flash, per consentire di aggiungere ulteriori informazioni.

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

Nel modello, questi messaggi sono disponibili nella variabile `$flashes` come oggetti `stdClass`, che contengono le proprietà `message` (testo del messaggio), `type` (tipo di messaggio) e possono contenere le già citate informazioni sull'utente. Li disegniamo come segue:

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


Errore 404 ecc. .[#toc-error-404-etc]
=====================================

Quando non possiamo soddisfare la richiesta, perché ad esempio l'articolo che vogliamo visualizzare non esiste nel database, lanceremo l'errore 404 usando il metodo `error(?string $message = null, int $httpCode = 404)`, che rappresenta l'errore HTTP 404:

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

Il codice di errore HTTP può essere passato come secondo parametro; il valore predefinito è 404. Il metodo funziona lanciando l'eccezione `Nette\Application\BadRequestException`, dopo di che `Application` passa il controllo al presentatore dell'errore. Si tratta di un presentatore che ha il compito di visualizzare una pagina che informa dell'errore.
Il presentatore di errori è impostato nella [configurazione dell'applicazione |configuration].


Invio di JSON .[#toc-sending-json]
==================================

Esempio di metodo-azione che invia dati in formato JSON ed esce dal presentatore:

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


Parametri di richiesta .[#toc-request-parameters]
=================================================

Il presentatore, così come ogni componente, ottiene i suoi parametri dalla richiesta HTTP. I loro valori possono essere recuperati con il metodo `getParameter($name)` o `getParameters()`. I valori sono stringhe o array di stringhe, essenzialmente dati grezzi ottenuti direttamente dall'URL.

Per maggiore comodità, si consiglia di rendere i parametri accessibili tramite proprietà. È sufficiente annotarli con l'attributo `#[Parameter]` attributo:

```php
use Nette\Application\Attributes\Parameter;  // questa linea è importante

class HomePresenter extends Nette\Application\UI\Presenter
{
	#[Parameter]
	public string $theme; // deve essere pubblica
}
```

Per le proprietà, si consiglia di specificare il tipo di dati (ad esempio, `string`). Nette calcolerà automaticamente il valore in base ad esso. Anche i valori dei parametri possono essere [convalidati |#Validation of Parameters].

Quando si crea un collegamento, è possibile impostare direttamente il valore dei parametri:

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


Parametri persistenti .[#toc-persistent-parameters]
===================================================

I parametri persistenti sono usati per mantenere lo stato tra diverse richieste. Il loro valore rimane invariato anche dopo aver cliccato su un link. A differenza dei dati di sessione, vengono passati nell'URL. Questo è completamente automatico, quindi non è necessario dichiararli esplicitamente in `link()` o `n:href`.

Un esempio di utilizzo? Avete un'applicazione multilingue. La lingua attuale è un parametro che deve sempre far parte dell'URL. Ma sarebbe incredibilmente noioso includerlo in ogni link. Perciò lo si rende un parametro persistente, chiamato `lang`, che si autoalimenta. Forte!

Creare un parametro persistente è estremamente facile in Nette. Basta creare una proprietà pubblica e contrassegnarla con l'attributo: (in precedenza si usava `/** @persistent */` )

```php
use Nette\Application\Attributes\Persistent; // questa linea è importante

class ProductPresenter extends Nette\Application\UI\Presenter
{
	#[Persistent]
	public string $lang; // deve essere pubblico
}
```

Se `$this->lang` ha un valore come `'en'`, i link creati con `link()` o `n:href` conterranno anche il parametro `lang=en`. E quando il link viene cliccato, sarà di nuovo `$this->lang = 'en'`.

Per le proprietà, si consiglia di includere il tipo di dati (ad esempio, `string`) e si può anche includere un valore predefinito. I valori dei parametri possono essere [convalidati |#Validation of Parameters].

I parametri persistenti vengono passati per impostazione predefinita tra tutte le azioni di un determinato presentatore. Per passarli tra più presentatori, è necessario definirli:

- in un antenato comune dal quale i presentatori ereditano
- nel tratto che i presentatori utilizzano:

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

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

È possibile modificare il valore di un parametro persistente durante la creazione di un collegamento:

```latte
<a n:href="Product:show $id, lang: cs">detail in Czech</a>
```

Oppure può essere *ripristinato*, cioè rimosso dall'URL. In questo caso, assumerà il valore predefinito:

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


Componenti interattivi .[#toc-interactive-components]
=====================================================

I presentatori hanno un sistema di componenti incorporato. I componenti sono unità separate e riutilizzabili che vengono inserite nei presentatori. Possono essere [moduli |forms:in-presenter], griglie di dati, menu, qualsiasi cosa abbia senso usare ripetutamente.

Come si posizionano i componenti e come si utilizzano successivamente nel presentatore? Questo è spiegato nel capitolo [Componenti |Components]. Scoprirete anche cosa hanno a che fare con Hollywood.

Dove posso trovare alcuni componenti? Alla pagina [Componenti |https://componette.org] si possono trovare alcuni componenti open-source e altri addons per Nette, realizzati e condivisi dalla comunità di Nette Framework.


Approfondimento .[#toc-going-deeper]
====================================

.[tip]
Quanto mostrato finora in questo capitolo sarà probabilmente sufficiente. Le righe che seguono sono destinate a chi è interessato ad approfondire i presentatori e vuole sapere tutto.


Convalida dei parametri .[#toc-validation-of-parameters]
--------------------------------------------------------

I valori dei [parametri della richiesta |#request parameters] e dei [parametri persistenti |#persistent parameters] ricevuti dagli URL vengono scritti nelle proprietà dal metodo `loadState()`. Il metodo controlla anche se il tipo di dati specificato nella proprietà corrisponde, altrimenti risponde con un errore 404 e la pagina non viene visualizzata.

Non fidarsi mai ciecamente dei parametri, perché possono essere facilmente sovrascritti dall'utente nell'URL. Ad esempio, è così che controlliamo se `$this->lang` è tra le lingue supportate. Un buon modo per farlo è sovrascrivere il metodo `loadState()` citato in precedenza:

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

	public function loadState(array $params): void
	{
		parent::loadState($params); // qui viene impostato $this->lang
		// segue il controllo del valore dell'utente:
		if (!in_array($this->lang, ['en', 'cs'])) {
			$this->error();
		}
	}
}
```


Salvare e ripristinare la richiesta .[#toc-save-and-restore-the-request]
------------------------------------------------------------------------

La richiesta che il presentatore gestisce è un oggetto [api:Nette\Application\Request] e viene restituita dal metodo del presentatore `getRequest()`.

È possibile salvare la richiesta corrente in una sessione o ripristinarla dalla sessione e lasciare che il presentatore la esegua di nuovo. Ciò è utile, ad esempio, quando un utente compila un modulo e il suo login scade. Per non perdere i dati, prima di reindirizzare alla pagina di accesso, salviamo la richiesta corrente nella sessione con il metodo `$reqId = $this->storeRequest()`, che restituisce un identificatore sotto forma di stringa breve e lo passa come parametro al presentatore di accesso.

Dopo l'accesso, chiamiamo il metodo `$this->restoreRequest($reqId)`, che preleva la richiesta dalla sessione e la inoltra ad essa. Il metodo verifica che la richiesta sia stata creata dallo stesso utente che ha effettuato l'accesso. Se un altro utente accede o la chiave non è valida, non fa nulla e il programma continua.

Vedere il ricettario [Come tornare a una pagina precedente |best-practices:restore-request].


Canonizzazione .[#toc-canonization]
-----------------------------------

I presentatori hanno una caratteristica davvero eccezionale che migliora la SEO (ottimizzazione della ricercabilità su Internet). Impediscono automaticamente l'esistenza di contenuti duplicati su URL diversi. Se più URL conducono a una determinata destinazione, ad esempio `/index` e `/index?page=1`, il framework ne designa uno come principale (canonico) e reindirizza gli altri verso di esso utilizzando il codice HTTP 301. In questo modo, i motori di ricerca non indicizzano le pagine due volte e non ne indeboliscono il page rank.

Questo processo è chiamato canonizzazione. L'URL canonico è l'URL generato dal [router |routing], di solito il primo percorso appropriato della collezione.

La canonizzazione è attiva per impostazione predefinita e può essere disattivata tramite `$this->autoCanonicalize = false`.

Il reindirizzamento non avviene con una richiesta AJAX o POST, perché comporterebbe una perdita di dati o non avrebbe alcun valore aggiunto dal punto di vista SEO.

Si può anche invocare la canonizzazione manualmente con il metodo `canonicalize()`, che, come il metodo `link()`, riceve come argomenti il presentatore, le azioni e i parametri. Crea un link e lo confronta con l'URL corrente. Se è diverso, reindirizza al link generato.

```php
public function actionShow(int $id, ?string $slug = null): void
{
	$realSlug = $this->facade->getSlugForId($id);
	// reindirizza se $slug è diverso da $realSlug
	$this->canonicalize('Product:show', [$id, $realSlug]);
}
```


Eventi .[#toc-events]
---------------------

Oltre ai metodi `startup()`, `beforeRender()` e `shutdown()`, che vengono richiamati durante il ciclo di vita del presentatore, è possibile definire altre funzioni da richiamare automaticamente. Il presentatore definisce i cosiddetti [eventi |nette:glossary#events], i cui gestori vengono aggiunti agli array `$onStartup`, `$onRender` e `$onShutdown`.

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

I gestori nell'array `$onStartup` vengono chiamati subito prima del metodo `startup()`, poi `$onRender` tra `beforeRender()` e . `render<View>()` e infine `$onShutdown` subito prima di `shutdown()`.


Le risposte .[#toc-responses]
-----------------------------

La risposta restituita dal presentatore è un oggetto che implementa l'interfaccia [api:Nette\Application\Response]. Esiste una serie di risposte già pronte:

- [api:Nette\Application\Responses\CallbackResponse] - invia un callback
- [api:Nette\Application\Responses\FileResponse] - invia il file
- [api:Nette\Application\Responses\ForwardResponse] - invia ()
- [api:Nette\Application\Responses\JsonResponse] - invia JSON
- [api:Nette\Application\Responses\RedirectResponse] - reindirizza
- [api:Nette\Application\Responses\TextResponse] - invia testo
- [api:Nette\Application\Responses\VoidResponse] - risposta vuota

Le risposte sono inviate con il metodo `sendResponse()`:

```php
use Nette\Application\Responses;

// Testo normale
$this->sendResponse(new Responses\TextResponse('Hello Nette!'));

// Invia un file
$this->sendResponse(new Responses\FileResponse(__DIR__ . '/invoice.pdf', 'Invoice13.pdf'));

// Invia un callback
$callback = function (Nette\Http\IRequest $httpRequest, Nette\Http\IResponse $httpResponse) {
	if ($httpResponse->getHeader('Content-Type') === 'text/html') {
		echo '<h1>Ciao</h1>';
	}
};
$this->sendResponse(new Responses\CallbackResponse($callback));
```


Limitazione dell'accesso tramite `#[Requires]` .[#toc-access-restriction-using-requires]{data-version:3.2.2}
------------------------------------------------------------------------------------------------------------

L'attributo `#[Requires]` fornisce opzioni avanzate per limitare l'accesso ai presentatori e ai loro metodi. Può essere usato per specificare metodi HTTP, richiedere richieste AJAX, limitare l'accesso alla stessa origine e limitare l'accesso al solo inoltro. L'attributo può essere applicato alle classi di presentatori e ai singoli metodi, come ad esempio `action<Action>()`, `render<View>()`, `handle<Signal>()`, e `createComponent<Name>()`.

È possibile specificare queste restrizioni:
- sui metodi HTTP: `#[Requires(methods: ['GET', 'POST'])]`
- che richiedono una richiesta AJAX: `#[Requires(ajax: true)]`
- accesso solo dalla stessa origine: `#[Requires(sameOrigin: true)]`
- accesso solo tramite inoltro: `#[Requires(forward: true)]`
- restrizioni su azioni specifiche: `#[Requires(actions: 'default')]`

Per i dettagli, vedere [Come usare l'attributo Requires |best-practices:attribute-requires].


Controllo del metodo HTTP .[#toc-http-method-check]
---------------------------------------------------

In Nette, i presentatori verificano automaticamente il metodo HTTP di ogni richiesta in arrivo, principalmente per motivi di sicurezza. Per impostazione predefinita, sono ammessi i metodi `GET`, `POST`, `HEAD`, `PUT`, `DELETE`, `PATCH`.

Se si desidera abilitare altri metodi, come ad esempio `OPTIONS`, è possibile utilizzare l'attributo `#[Requires]` (dall'applicazione Nette v3.2):

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

Nella versione 3.1, la verifica viene eseguita in `checkHttpMethod()`, che controlla se il metodo specificato nella richiesta è incluso nell'array `$presenter->allowedMethods`. Aggiungere un metodo come questo:

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

È fondamentale sottolineare che se si abilita il metodo `OPTIONS`, è necessario gestirlo correttamente anche nel presenter. Questo metodo è spesso usato come una cosiddetta richiesta di preflight, che i browser inviano automaticamente prima della richiesta vera e propria quando è necessario determinare se la richiesta è consentita dal punto di vista della politica CORS (Cross-Origin Resource Sharing). Se si consente questo metodo ma non si implementa una risposta appropriata, si possono creare incongruenze e potenziali problemi di sicurezza.


Ulteriori letture .[#toc-further-reading]
=========================================

- [Iniettare metodi e attributi |best-practices:inject-method-attribute]
- [Comporre presentatori da tratti |best-practices:presenter-traits]
- [Passare le impostazioni ai presentatori |best-practices:passing-settings-to-presenters]
- [Come tornare a una pagina precedente |best-practices:restore-request]