Presenters

A presenter is an object, that takes the request as translated by the router from the HTTP request and generates a response. The response can be an HTML page, picture, XML document, file, JSON, redirect or whatever you think of.

By a presenter, it is usually meant a descendant of the Nette\Application\UI\Presenter class. By requests, it runs appropriate actions and renders templates.

Life Cycle of Presenter

We know by now that a presenter action causes invoking render<Action> method, thus for example renderShow. But it's not the only method that gets invoked. When writing presenters, we can write the following methods:

startup()

Method startup() gets invoked immediately after the presenter is created. It initializes variables or checks user privileges.

If you write your own startup() method, don't forget to call its parent parent::startup().

action<Action>()

Analogous to the method render<View>(). There are situations when the presenter executes some specific action (authenticates the user, writes to database) and then redirects to somewhere else. To call it render would be inappropriate because nothing is rendered. Because of that, there is an alternative called action.

It's important to know that the method action<Action>() gets called before render<View>(). It can even decide to change what render method gets invoked, by calling $this->setView('otherView') (renderOtherView() will get invoked).

handle<Signal>()

Method handles so-called signals aka subrequests. Designed mainly for components and handling of AJAX requests. Processing of forms is also performed on this level.

beforeRender()

Method beforeRender, as the name suggests, gets invoked before render<View>() and it can contain for example setup of template, passing variables to template common for more views and so on.

render<View>()

Usually passes required data to templates.

shutdown()

Gets invoked at the end of the presenters life cycle.

More accurate would be to say, that we were talking about life cycle of the class Nette\Application\UI\Presenter, from which presenters are inherited most often. In general, a presenter is any class implementing the simple interface Nette\Application\IPresenter.

Sending Responses

We can terminate a presenter at any time during his life cycle and send a different response than the default rendering of the template.

• terminate presenter by method: $presenter->terminate()
• terminate presenter and immediate render the template: $presenter->sendTemplate()
• terminate presenter and dispatch of the payload: $presenter->sendPayload() (for AJAX)
• terminate presenter and dispatch of own response: $presenter->sendResponse($response)
• terminate presenter and dispatch of JSON: $presenter->sendJson($data)
• terminate presenter and dispatch of error message: $presenter->error($message, $httpCode)

Example of sending JSON:

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

Examples of using the sendResponse method:

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

// Sends a file
$this->sendResponse(new Nette\Application\Responses\FileResponse(__DIR__ . '/invoice.pdf', 'Invoice13.pdf'));

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

A presenter can be terminated also by redirecting or forwarding, see below.

You can find a repository of presenter responses on Componette.

Template rendering

The presenter will deduce the path to the template file from a few simple rules. It will try, for presenter Product and action show, if one of these files exists:

• templates/Product/show.latte
• templates/Product.show.latte

Presenter will also try to search for a layout (that is optional):

• templates/Product/@layout.latte
• templates/Product.@layout.latte
• templates/@layout.latte layout shared by multiple presenters

You can change the way of searching the templates by overriding the formatTemplateFiles or formatLayoutTemplateFiles methods.

Presenters and its components pass a few useful variables to the templates:

• $basePath is an absolute URL path to root dir (for example /CD-collection)
• $baseUrl is an absolute URL to root dir (for example http://localhost/CD-collection)
• $user is an object representing the user
• $presenter is the current presenter
• $control is the current component or presenter
• $flashes list of messages sent by method flashMessage()

You can read more details about template language Latte in a separate chapter.

Actually it's not hard at all! When you're requesting an action, for example Homepage:default, then

1. an object of class HomepagePresenter will be created
2. method renderDefault() will be called (if it exists, but it doesn't have to)
3. template, for example templates/Homepage/default.latte with layout, for example templates/@layout.latte, will be rendered

and in template we can create a link to mentioned Product:show($id), roughly like this:

<a n:href="Product:show $productId">product detail</a>

Redirection

There are two methods redirect() and forward() for jumping to another presenter, which have similar syntax as mentioned link(). For example, after submitting a form and writing to the database, we will redirect to the product's detail by calling:

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

While forward() will pass to new action without redirecting, method redirect() will redirect the browser with HTTP code 302 or 303. This way we will redirect permanently with code 301:

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

To go to URLs outside of your application, you can redirect using redirectUrl():

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

Redirection immediately terminates activity of the presenter by throwing the so-called terminating exception Nette\Application\AbortException.

Sometimes, before redirection, we want to send a so-called flash message. That's a message that will appear after redirection in template.

Error 404, etc.

When we can't fulfill the request because for example the record is missing in the database, we will throw an exception Nette\Application\BadRequestException using method error(), which represents HTTP error 404:

public function renderShow(int $id): void
{
	$product = $this->productRepository->getProduct($id);
	if (!$product) {
		$this->error();
	}

	// ...
}

When a user is not authorized to see the page, we will throw a Nette\Application\ForbiddenRequestException exception (error 403). Other error codes can be returned using the second argument of Nette\Application\BadRequestException.

Flash Messages

These are messages informing about a result of some operation. An important feature of flash messages is that they are available in the template, even after redirection. Even when displayed, they are available for three seconds – in case that a user would unintentionally refresh the page – thus messages will not be lost.

Just call the flashMessage() method and presenter will take care of passing the message to the template. The first argument is the text of the message and the second optional argument is its type (error, warning, info etc.). The method flashMessage() returns an instance of flash message, to allow us to add more information.

public function deleteFormSubmitted(): void
{
	// ... model asks for deletion of record ...

	// we will pass the flash message
	$this->flashMessage('Item was removed.');

	$this->redirect(...); // and redirect
}

These messages are available in templates variable $flashes as anonymous objects, that contains a message and type properties and they can even contain previously mentioned user-defined information. They can be rendered for example like this:

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

Usage of Model Classes

As we've said before, the model is a whole layer composed of many classes, where each one is taking care of one part of application logic. If we'd have for example a model App\ArticleRepository, which would take care of loading and saving articles, we may ask for it in a presenter using Dependency Injection, assuming we've properly registered it as a service in DI Container.

class ArticlePresenter extends Nette\Application\UI\Presenter
{
	/** @var ArticleRepository */
	private $articles;

	public function __construct(ArticleRepository $articles)
	{
		$this->articles = $articles;
	}

	public function renderShow(int $id): void
	{
		$this->template->article = $this->articles->find($id);
	}
}

Thanks to this mechanism, we can use the service right away, without caring where it came from or trying to instantiate it because we're sure that it will be passed to the property, as long as it's correctly registered in the DI Container.

Without using a constructor you can only inject into the public properties of classes with annotation @inject.

Presenter and Components

When we talk about presenters, then under the term components we usually mean descendants of class Control.

Presenter Nette\Application\UI\Presenter by itself is descendant of class Control, so there is a major similarity between components and presenter. But UI\Control (and thus even UI\Presenter) is primarily a so-called component container. Which means that you can add to it other components. Just like we add to form inputs (text field, button, …). And just like with forms, you can access them through brackets:

// attach component to presenter
$presenter['mymenu'] = new MenuControl;

// get component from presenter and render it
$presenter['mymenu']->render();

Attaching the component to the presenter (binding them) you will be able to:

• create links in component
• use signals
• use persistent parameters in components

When you don't need any of these features, you don't have to bind the component with the presenter.

Component Factories

Component factories are an elegant way to create components only when they are really needed (lazy / on-demand). The whole magic is in implementation of a method called createComponent<Name>(), where <Name> is the name of component, that will create and return the desired component. This component is then attached to the presenter. The method createComponent<Name>() is optionally passed the $name of the component, that is being created, as an argument.

class DefaultPresenter extends Nette\Application\UI\Presenter
{
	public function renderDefault(): void
	{
		$menu = $this['menu']; // access to component
		// if this was the first access, method createComponentMenu() will be called
		// ...
	}

	protected function createComponentMenu(): MenuControl
	{
		// create and configure component
		$menu = new MenuControl;
		$menu->items = $this->item;
		// and return it
		return $menu;
	}
}

The first letter of a component name is always lower case, despite that the first letter in the factory name is upper case.

Because all components are created in separate methods, the code is cleaner and easier to read.

We never call factories directly, they get called automatically, when we use components for the first time. Thanks to that, a component is created at the right moment, and only if it's really needed. If we wouldn't use the component (for example on some AJAX request, where we return only part of the page, or when parts are cached), it wouldn't even be created and we save performance of the server.

You can access and render component using tag {control}. So there is no need of manually passing the components to template.

<h2>Edit form</h2>

{control editForm}

You can read more detailed information about components on a separate page.

Persistent Parameters

Except for classic parameters, that we know by now, there are so-called persistent parameters. Those are different in a very essential way: they are passed through requests automatically. That means, we don't have to explicitly mention them in links, but they are passed anyway.

When your application has multiple language variants passing the actual language in every link will be incredibly tiring. But that's not needed with Nette Framework. You can simply mark the $lang parameter as persistent just like this:

class ProductPresenter extends Nette\Application\UI\Presenter
{
	/** @persistent */
	public $lang;

	...

If the actual value of parameter $lang will be 'en', the into the link

<a n:href="Product:show $productId">product detail</a>

the parameter lang => en will be passed automatically. Great!

But we can also add parameter lang and by that, change its value:

<a n:href="Product:show $productId, lang => cs">detail in Czech language</a>

The parameter will be accessible in the class variable $lang in objects of ProductPresenter and it can be accessed through $this->lang. We can even set the default value of the persistent parameter to presenter class. If the parameter value will correspond to the default value, it will not be passed in a URL.

A persistent variable must be declared as public.

Persistence reflects the hierarchy of presenter classes, thus parameter defined in specific presenter will be automatically taken into account in every single presenter inheriting from it.

Persistent Components

Not only parameters but also components can be persistent. Their state is then passed around when jumping to another presenter, just like with persistent parameters. We mark persistent components with this annotation (here we mark components calendar and menu):

/**
 * @persistent(calendar, menu)
 */
class DefaultPresenter extends Nette\Application\UI\Presenter
{
	// ...
}

You don't have to mark subcomponents as persistent, they are persistent automatically.

Where Can I Get Some Components?

On page Add-ons, plugins and components you can find some open-source components that were made and shared by the community of Nette Framework. Nette Foundation is not liable for them.

Configuration

We can modify application settings in the configuration file, under application section. See application configuration.