Chapter 7. Actions and views

Table of Contents

Introduction
Actions
Views
Layout
Controlling views
View's filename extension
Do not render the view from the action
Using a custom rendering engine
Calling actions or views programmatically
Executing actions
Rendering views and files

Introduction

Without using Atomik, one way of doing things would have been to create a file per page. The page logic (i.e. connecting to a database, handling form data...) would have been at the top of the file followed by the HTML.

Example 7.1. A php script, the old way

				
<?php
	if (count($_POST)) {
		echo 'Form data received!';
	}
?>
<form>
	<input type="text" name="data" />
	<input type="submit" value="send" />
</form>
			

This is BAD!! The application logic and the presentation layer should always be separated.

Now let's imagine that rather than directly doing both part in the same file we split it. We would have three file: one with the logic, one with the HTML and one that include both.

Example 7.2. Splitting into multiple files

page_logic.php

				
<?php
if (count($_POST)) {
	echo 'Form data received!';
}
			

page_html.php

				
<form>
	<input type="text" name="data" />
	<input type="submit" value="send" />
</form>
			

page.php

				
<?php
include 'page_logic.php';
include 'page_html.php';
			

Now replace the third file (the one with the includes) with Atomik and you'll have the concept behind Atomik. The logic script is named an action and the html a view.

Actions

Actions are stored in the app/actions directory. Both the action and the view filename must have the same name. Action files must have the “php” extension.

The content of the action file is free. It can be anything you want. So you just do your logic as you used to.

Note

Be aware that actions run in their own scope and not in the global scope as you might think.

Variables declared in the action are forwarded to the view. If you want to keep some variables private (i.e. which will only be available in your action) prefixed them with an underscore.

Example 7.3. Private variables in actions

				
<?php
$myPublicVariable = 'value';
$_myPrivateVariable = 'secret';
			

Note

You shouldn't use echo or write any HTML code inside an action. As said before, the goal of an action is to separate the logic from the presentation. Thus mix-in both in the action file would be a non-sense!

You can use folders to organize your actions.

If you would like to exit the application, avoid using exit() and prefer Atomik::end() so Atomik can smoothly exit your application.

Views

Views are stored in the app/views directory. The file extension is by default “phtml”.

The content of the view file is, as the action file, free. It should mostly be text or HTML (or any presentation content, such as XML).

PHP can be used to print variables from the action or to provide presentation logic like loops.

Example 7.4. Example view

				
<html>
	<head>
		<title>Example</title>
	</head>
	<body>
		<?php echo $myPublicVariable; ?>
	</body>
</html>
			

Figure 7.1. A little schema to sum up!

A little schema to sum up!

Layout

It is common in websites that all pages share the same layout. Atomik allows you to define a layout that will be used with all views.

The layout will be rendered after the view has been rendered. The output of the view will be pass to the layout as a variable named $contentForLayout. Layouts are rendered the same way as views.

Layouts can be placed in the app/views or app/layouts directories. The file extension is the same as the one for views.

The layout name to use has to be defined in the “layout” configuration key. If the value is false (which is the default), no layout will be used.

The layout can be disabled at runtime by calling Atomik::disableLayout(). It can later be re-enabled by passing false as argument to the same method.

Example 7.5. Example layout

A layout file named _layout.phtml in the app/views directory.

				
<html>
	<head>
		<title>My website</title>
	</head>
	<body>
		<h1>My website</h1>
		<div id="content">
			<?php echo $contentForLayout; ?>
		</div>
	</body>
</html>
			

In the bootstrap file

				
Atomik::set('layout', '_layout');
			

Mutliple layouts can also be used. Just use an array instead of a string in the configuration key. Layouts will be rendered in reverse order (the first one in the array wrap the second, the second the third, ...).

Controlling views

View's filename extension

The default filename's extension for views is “phtml” as said before. This can be change using the configuration key named “atomik/views/file_extension”.

Do not render the view from the action

While the action is executing, you may want to avoid rendering the associated view. This can easily be done by calling Atomik::noRender() from your action.

Using a custom rendering engine

The default rendering process only uses php's include function. You may however want to use a template engine for example. This is possible by specifying a callback in the “atomik/views/engine” configuration key.

The callback will receive two parameters: the first one will be the filename and the second an array containing the view variables.

Example 7.6. Using a custom rendering engine

					
function myCustomRenderingEngine($filename, $vars)
{
	// your custom engine
	return $renderedContent;
}

Atomik::set('atomik/views/engine', 'myCustomRenderingEngine');
				

The custom rendering engine will be used whenever Atomik::render(), Atomik::renderFile() or Atomik::renderLayout() is used.

Calling actions or views programmatically

When executing a request, the action and/or the view associated to it are automatically called. You can however call other actions or render other views using Atomik's API.

The most useful use of this it to render partial views, small part of presentation code that is reusable.

Executing actions

To execute an action use the Atomik::execute() method. It takes as first argument the action name.

By default, if a view with the same name is found, it is rendered and the return value of the execute() method is the view output.

If no view is found or false is used as second argument, the return value is an array containing all “public” variables from the action.

Example 7.7. Calling an action programmatically

					
$viewOutput = Atomik::execute('myAction');
$variables = Atomik::execute('myAction', false);
				

Note

Calling an action using Atomik::execute() does not mean an action file must exist. However, in this case, a view file with the same name must exists.

Rendering views and files

To render a view use the Atomik::render() method.

It takes as first argument the view name and optionally as second argument an array of key/value pairs representing variables.

The method returns the view output.

Example 7.8. Rendering a view programmatically

					
$viewOutput = Atomik::render('myView');
$viewOutput = Atomik::render('myView', array('var' => 'value'));
				

It is also possible to render any file using Atomik::renderFile(). It takes as first parameter a filename. Variables can also be passed like with Atomik::render().