Plain-old 'include'

When working with your view templates, you've probably separated templates into many smaller ones which you can then just include to a parent template with PHP's include. This works often really well. Let's say that $this->entry holds some data that should be displayed in a template called _header.php. In Solar, you can do this properly with the template() method, like this:

<?php
// entry.php:

// $this->entry object holds data to be displayed in _header.php

// include _header.php to the flow of this view
include $this->template('_header');

// other code follows to complete entry.php
// ...
?>

template() method searches for _header.php in the template dir stack and just returns the path to it, but let's not go into details with that :-). Anyways, the point here is the use of include which means that all the variables that _header.php uses must be made available in entry.php exactly the way _header.php wants them. In practise this means that _header.php is more-or-less tied to entry.php. It must access all the variables exactly by the name they've been set up in entry.php.

You are most likely to need the logic in _header.php in another template. But what if in that template's scope the variables are declared with completely different names than they are in entry.php? For example, $this->entry object could be part of a collection of objects, say, in $this->entries[4]. You would need to add a lot of messy code just before calling include to rename the variable correctly for _header.php.

Enter partial().

Solar_View::partial()

Just like directly included templates, partials are re-usable pieces of template code that you include into the template flow. The thing that makes partials much cooler than just plain include is that partials execute in their own scope rather than in the same scope as the template from which they were included (in this case entry.php).

Now, rather than naming variables correctly for the to-be-included file, you give it all that it needs as parameters, just like you give parameters to a function or method. The code would look something like this:

<?php
// entry.php:

// run _header.php in it's own scope and echo the result
echo $this->partial('_header', $this->entry);

// other code follows to complete entry.php
// ...
?>

Now our template code is in a sandbox. It's just like a normal method call, all template code now runs in it's own scope not interfering with other variables. If you pass an object as the second param, it will be accessed with $header in _header.php. Give it an assoc array and it will be extract()ed to the local scope of the template.

Notice how instead of including the result we echo it. partial() turns on output buffering, includes the template, and then finally cleares the buffer and returns output for the template.

Conclusion

Solar_View::partial() is the best tool in Solar for creating reusable partial templates. However, it's also pretty slow compared to plain include. Still, if you find yourself using many little templates to create the whole page I suggest taking a look at partial().