Views and templates

What are Views and what are templates?

Renderers and Rendering

Any class that provides a render() and set() methods can act as a renderer. The Response and View use this polymorphism to enable renders to be attached in any arrangement. A number of classes provide a setRenderer() that allows the render to be set at run-time. Also if you assign a renderer object to the View using the set() method, the render's render() method will not be called until the View's render() method is called. This allows lazy rendering when the templates to render are specified, but only loaded and processed if used.

Difference between Views and templates

Both View and template classes have a render() method that returns the output. Views add the ability to:

set HTTP headers with the setHeader() method
set redirects with the setRedirect() method
the renderer used by the render() method can be replaced with any View or template object (or any object with set() and render() methods)

View functionality

The base View class in Skeleton is A_Http_View. There is also a A_Http_Response class (that extends A_Http_View) for use as the root View object. It can be used as a View, plus it gathers and outputs HTTP headers in addition to the output.

The View class has three ways to produce output:

Set the internal content buffer directly

You may set the buffer directly using the setContent() method. The method takes a string that will be returned when render() is called.
```
$view = new A_Http_View();
$view->setContent('Hello world!');
echo $view->render();
// Output: Hello world!
```
Specify a PHP template to be included

You may specify a PHP template using the setTemplate() method. The method takes a string that is the base name of the template requested. For example, calling setTemplate('foo') will load 'templates/foo.php'. Variables can be made available by calling the set() method. The output of the included PHP template will be returned when render() is called.
File: templates/foo.php
```
Hello <?php echo $this->bar; ?>!
```
```
$view = new A_Http_View();
$view->setTemplate('foo');
$view->set('bar', 'world');
echo $view->render();
// Output: Hello world!
```

Give the View a renderer object to render the output

You may give the View an object to render the output using the setRenderer() method. The method takes an object that will have render() and set() methods. When the View render() method is called, it proxies the call to the renderer's render() method.

File: templates/foo.html

Hello {bar}!

// create a template object to render the template
$template = new A_Template_Strreplace('templates/foo.html');
$template->set('bar', 'world');

$view = new A_Http_View();
$view->setRenderer($template);		// set the template as the View's renderer
echo $view->render();				// calls $template->render() and returns output
// Output: Hello world!

View Partials

A Partial is a sub-template that can be used as a part of the full content rendered by the View. Partial functions return or set() as string value.

The template name passed to the partial methods is assumed to be in the 'templates/' directory. A '/' in the template name specifies template in a sub-directory of the 'template/' directory. The '.php' extension is optional.

partial ()

The partial() method takes the name of a template and a optional array of key/value pairs to assign in the template.

$view = new A_Http_View();
$view->set('greeting', 'Hello');							// set the value of a $foo variable in the template
echo $view->partial('bar');									// returns output of template 'templates/bar.php'
// Output: Hello world!
echo $view->partial('bar', array('greeting'=>'Goodbye');	// optional way to set template variables
// Output: Goodbye world!

partialLoop ()

The partialLoop() method takes the name of a template and an array of data assign in the template.

The first mode for partialLoop() is to render the template with the variable named set for each value in the array:

echo $view->partialLoop('bar', 'greeting', array('Hello', 'Goodbye');		// optional way to set template variables
// Output: Hello world!
//         Goodbye world!

The second mode for partialLoop() is to render the template multiple times, but each array element is an array of key/value pairs:

echo $view->partialLoop('bar', array( array('greeting'=>'Hello', 'place'=>'world'), array('greeting'=>'Goodbye', 'place'=>'planet') );
// Output: Goodbye world!
//         Goodbye planet!

setPartial ()

Shortcut for calling the set() method with the output of a partial.

$view->setPartial('title', 'bar');
// is the same as
$view->set('title', $view->partial('bar'));

setPartialLoop ()

Shortcut for calling the set() method with the output of a partial loop.

$view->setPartialLoop('title', 'bar', 'greeting', array('Hello', 'Goodbye'));
// is the same as
$view->set('title', $view->partialLoop('bar', 'greeting', array('Hello', 'Goodbye')));

The Response

The A_Http_Response class extends A_Http_View class, so it may be used as the root View object if you have a tree of Views/templates. Or it can be used as the only View object in a single View object solution. The Response is different from the View class in that its render() method gathers and outputs HTTP headers in addition to normal output.

Templates

A template class is any class with render() and set() methods. Skeleton provides several simple template classes, plus Adapters to popular template systems (See section Template Classes). You can wrap any template code you like with a render() and set() method, and use it as a renderer in the Skeleton framework.