Using Templates with the Action Controller

About 2 min

Using Templates with the Action Controller

Hazaar's Action controller provides a powerful and flexible way to render views and layouts in your application. By default, when you extend Hazaar\Controller\Action, your controller will use a layout template and can easily render sub-views. This document explains how to use the Action controller with layout and view templates, including practical examples.

What is the Action Controller?

The Hazaar\Controller\Action class is a base controller that provides built-in support for layouts and views. When you extend this controller, your actions automatically render views and can be wrapped in a layout template. This makes it easy to create consistent page structures and reuse common UI elements.

About Hazaar Templates

Hazaar uses Smarty as its template engine. All layout and view templates (*.tpl files) are written using Smarty syntax, which supports variables, template tags, and powerful logic for dynamic content. This allows you to:

Use variables like {$application->config} and {$hazaar.version}
Include template tags such as {url}
Write conditional logic and loops directly in your templates

For more information on Smarty syntax, see the Smarty documentation.

Layouts and Views: How it Works

Layout Template: The layout is a wrapper for your page content. It typically includes the HTML <head>, navigation, footer, and a placeholder for the main content. By default, Hazaar looks for app.tpl in your views directory.
View Template: The view is the main content for a specific action. For example, the index action in your controller will render index.tpl.
Sub-Views: You can add additional views to the layout using $this->view('viewname') in your controller action.

Example: Index Controller with Layout and View

Let's look at a practical example. Suppose you have the following files:

app/controllers/Index.php (Controller)
app/views/app.tpl (Layout template)
app/views/index.tpl (View template)

Controller: Index.php

<?php

namespace App\Controller;

use Hazaar\Controller\Action;

class Index extends Action
{
	public function index(): void
	{
		// This will render the 'index' view inside the layout
		$this->view('index');
	}
}

Layout Template: app.tpl

This template provides the overall page structure. It includes navigation, a footer, and a {layout} placeholder where the view content will be injected.

<!DOCTYPE html>
<html lang="en_AU">
<head>
	<title>{$application->config->app['name']}</title>
	<!-- ... other head elements ... -->
</head>
<body>
	<nav class="navbar navbar-expand-lg navbar-dark bg-dark">
		<!-- Navigation content -->
	</nav>
	<main role="main">{layout}</main>
	<footer class="bd-footer text-muted">
		<!-- Footer content -->
	</footer>
</body>
</html>

View Template: index.tpl

This template contains the main content for the index action. It will be rendered inside the layout's {layout} placeholder.

<div class="jumbotron">
	<div class="container">
		<h1 class="display-3">Welcome</h1>
		<p>
			Congratulations! You have successfully installed the Hazaar framework example application.
			You are currently running Hazaar version {$hazaar.version}.
		</p>
		<p>
			<a class="btn btn-hazaar btn-lg" href="https://hazaar.dev/docs" role="button">Learn more &raquo;</a>
		</p>
	</div>
</div>
<!-- ... more content ... -->

How Rendering Works

When you call $this->view('index') in your controller action:

Hazaar loads the app.tpl layout.
The {layout} placeholder in the layout is replaced with the content from index.tpl.
The final HTML is sent to the browser, combining the layout and view.

You can add multiple sub-views by calling $this->view('viewname') multiple times, and Hazaar will inject them into the layout as needed.

Customizing Layouts and Views

The default layout is set in your configuration file (app.php). For example:

return [
		'production' => [
				// ...
				'action' => [
						  'layout' => 'app', // Uses app.tpl as the layout
				],
				// ...
		],
		'development' => [
				'include' => 'production',
				// ...
		],
];

To use a different layout, change the value of 'layout' in the 'action' section. For example, 'layout' => 'app' will use app.tpl.

Views can access variables set in the controller using $this->set('key', $value).
Layouts and views support template tags like {url} and variables like {$application->config} for dynamic content.

Summary

Using the Action controller with layout and view templates in Hazaar allows you to build maintainable, consistent, and flexible web applications. Layouts provide a shared structure, while views deliver specific content for each action. This separation of concerns makes your code cleaner and your UI easier to manage.

For more information, see the Hazaar documentation and explore the example files in your project.