Fuel Documentation

Views

What is a view?

Views are files that present data to the browser. These files enable the separation of logic and presentation for your application. Views are typically html, javascript, or css but can contain variables passed into them from the controller.

Creating a view

In Fuel, Views are located in the fuel/app/views directory. Views can be located in subdirectories. Views are named by their directory path from the fuel/app/views and the file name. So a view file located fuel/app/views/user/join.php would be named user/join.

Example:

<html>
	<head>
		<title><?php echo $title; ?></title>
	</head>
	<body>
		Welcome, <?php echo $username; ?>.
	</body>
</html>

Using views

Views in the Fuel framework are very flexible. You can create a single view and nest views within other views. This can be done multiple ways.

Example View (fuel/app/views/home/index.php):

<html>
	<head>
		<title><?php echo $title; ?></title>
	</head>
	<body>
		Welcome, <?php echo $username; ?>.
	</body>
</html>

Method 1 (using example view above):

class Controller_Home extends Controller {

	$data = array(); //stores variables going to views

	$data['username'] = 'Joe14';
	$data['title'] = 'Home';

	//assign the view to browser output
	$this->response->body = View::factory('home/index', $data);
}

Method 2 (using example view above):

class Controller_Home extends Controller {
	//create the view
	$view = View::factory('home/index');

	//assign variables for the view
	$view->username = 'Joe14';
	$view->title = 'Home';

	//another way to assign variables for the view
	$view->set('username', 'Joe14');
	$view->set('title', 'Home');

	//assign the view to browser output
	$this->response->body = $view;
}

Security

By default Views use output encoding to sanitize anything you pass to them using Security::htmlentities(). If you want to pass something unfiltered you can use the method set($name, $value, false).

class Controller_Example extends Controller {

	public function action_index()
	{
		$view = \View::factory('example');

		// add it unfiltered just like you added
		// add it filtered, outputs: &lt;strong&gt;not bold because filtered&lt;/strong&gt;
		$view->title = '<strong>not bold because filtered</strong>';

		// add it unfiltered just like you added
		$view->set('title', '<strong>not bold because filtered</strong>', false);
	}
}

If you don't want your View to work like this change the public static property View::$auto_encode and set it to false. Now anything will be added unfiltered, if you do want some values filtered you can use set($name, $value, true).

Note on objects: Unless the passed object is of the type View, ViewModel or Closure it is expected to have a __toString() method and forced to be a string when output filtering is enabled. If you want to pass it anyway you need to use set($name, $value, false), but don't forget to filter what you use!
View & ViewModels are expected to contain HTML and take care of their own filtering, which is why they're not sanitized. Closures cannot be sanitized, and you should take care to ensure this is done within them if necessary.

Nesting Views

Views can also be nested, meaning views can contain other views. This can be done multiple ways.

Example Views

fuel/app/views/layout.php

<html>
	<head>
		<?php echo $head; ?>
	</head>
	<body>
		<?php echo $header; ?>
		<?php echo $content; ?>
		<?php echo $footer; ?>
	</body>
</html>

fuel/app/views/head.php

<title><?php echo $title; ?></title>

fuel/app/views/header.php

<div class="logo"></div>
<div class="logo_text"><?php echo $site_title; ?></div>

fuel/app/views/content.php

<title><?php echo $title; ?></title>
<div class="welcome_user">Welcome <?php echo $username; ?></div>

fuel/app/views/footer.php

<div class="footer">
	&copy; Copyright <?php echo date('Y');?> <?php echo $site_title; ?>
</div>

Method 1 (using example views above):

class Controller_Home extends Controller {

	public function action_index()
	{
		//create the view
		$view = View::factory('layout');

		//assign variables
		$view->username = 'Joe14';
		$view->set('title', 'Home');
		$view->site_title = 'My Website';

		//assign views as variables
		$view->head = View::factory('head');
		$view->header = View::factory('header');
		$view->content = View::factory('content');
		$view->footer = View::factory('footer');

		//assign to browser output
		$this->response->body = $view;
	}
}

Method 2 (using example views above):

class Controller_Home extends Controller {

	public function action_index()
	{
		//assign variables
		$data = array();
		$data['title'] = 'Home';
		$data['site_title'] = 'My Website';
		$data['username'] = 'Joe14';

		//assign views as variables
		$data['head'] = View::factory('head', $data)->render();
		$data['header'] = View::factory('header', $data)->render();
		$data['content'] = View::factory('content', $data)->render();
		$data['footer'] = View::factory('footer', $data)->render();

		//assign to browser output
		$this->output = View::factory('layout', $data);
	}
}

View Functions

factory($file = null, array $data = null, $auto_encode = null)

Creates and returns a new View object.

Static Yes
Parameters
Param Default Description
$file required View to be loaded from the views dir, without the .php file extension.
$data
array()
Array of variables to be used in the view.
$auto_encode
null
Output encoding, null means using global setting otherwise true/false to overwrite.
Returns View object
Example
// will load a view object for APPPATH/views/example.php
$view = View::factory('example');

set($key, $value = null, $encode = null)

Set a variable to be used in the view.

Static No
Parameters
Param Default Description
$key required Variable name.
$value required Value for the variable.
$encode
null
Output encoding, null means using global setting otherwise true/false to overwrite.
Returns Current View object
Example
// this is the same as $view->example = 'value';
$view->set('example', 'value');

// If you need HTML / Javascript passed you need to set the last param to false
// when output encoding is enabled.
$view->set('example', '<h1>Heading</h1>', false);

bind($key, $value = null)

Assigns a value by reference. The benefit of binding is that values can be altered without re-setting them. It is also possible to bind variables before they have values. Assigned values will be available as a variable within the view file.

Please note: these cannot be cleaned by output encoding and should thus be considered unsafe.

Static No
Parameters
Param Default Description
$key required Variable name.
$value required Value for the variable.
Returns Current View object
Example
// this is the same as $view->example = 'value';
$var = 'value';
$view->bind('example', $var);

// now if I change the value of $var it will also have been changed for usage in the view

set_global($key, $value = null, $encode = null)

Set a variable to be used in all views.

Static Yes
Parameters
Param Default Description
$key required Variable name.
$value required Value for the variable.
$encode
null
Output encoding, null means using global setting otherwise true/false to overwrite.
Returns void
Example
View::set_global('example', 'value');

// If you need HTML / Javascript passed you need to set the last param to false
// when output encoding is enabled.
View::set_global('sitename', '<h1>Heading</h1>', false);

bind_global($key, $value = null)

Assigns a value by reference, like bind().

Please note: these cannot be cleaned by output encoding and should thus be considered unsafe.

Static Yes
Parameters
Param Default Description
$key required Variable name.
$value required Value for the variable.
Returns Current View object
Example
// this is the same as $view->example = 'value';
$var = 'value';
View::bind_global('example', $var);

// now if I change the value of $var it will also have been changed for usage in the view

set_filename($file)

Change the file to be used for the view.

Static No
Parameters
Param Default Description
$file required View to be loaded from the views dir, without the .php file extension.
Returns Current View object
Example
$view = View::factory('example');

// now change the view to 'another' instead of 'example'
$view->set_filename('another');

public function render($file = null)

Load the view file, parse it and return its contents.

Static No
Parameters
Param Default Description
$file
null
When null the previously chosen view will be used, any other value will overwrite.
Returns String
Example
$view->render();
View::factory('home', $data)->render();