Use Layouts & Sub Templates

For the context of this article, I’ll be using Zend Framework 1 for usage examples (Why am I using Zend Framework 1 you ask? Because this post is based on an email I sent to my coworkers the other day who use Zend Framework 1). However, all major frameworks support something like this (Symfony2, Zend Framework 2, Laravel, Ruby on Rails, Django, etc).

Layouts

Layouts let you abstract the HTML code that is re-used on every page to a single (or several) re-usable template files. Using a layout system allows you to write cleaner, more DRY code. In Zend, layouts are located in the /application/layouts/scripts folder, and use the .phtml extension much like views. Generally, a layout will contain the HTML head/foot, and any parts of the page that may appear in every page (Top navigation for instance). Example of a Zend layout:

<!DOCTYPE html>
<html>

<head>
    <title>Some Title</title>
</head>

<body>
    <?php echo $this->layout()->content ?>
</body>

</html>

The part in the body will print out the contents of your regular view. That way, you only need to include the unique parts of a page in the view.

To select a layout in your controller, call the following code:

$this->_helper->layout->setLayout('admin');

This will use the layout file /application/layouts/scripts/admin.phtml.

Passing Variables To Your Layout

A common requirement is to pass unique variables to your layout, for example, the page title. This is easily accomplished. In your controller, use the following syntax to assign variables:

$this->_helper->layout->__set('title', 'My Page Title');

In your layout template, use the following syntax to access variables:

<?php echo Zend_Layout::getMvcInstance()->title ?>

Rendering Partial Templates

Commonly, you’ll have some code that is re-used in multiple places but is not something you can place in a layout. A great example of this would be a widget that appears on several pages but not all of them. For situations like this, you can use the render() function.

render() can be used in layouts or regular views. It will render the contents of a given .phtml template and return it. Here’s an example of its use:

<?php echo $this->render('widgets/products.phtml') ?>

The render() function loads a template relative to /application/views/scripts when used in a regular view, and /application/layouts/scripts when used in a layout.

Variables available in the current template are available in the rendered template as well.

The Partial Function

Also of note is the partial() function. It behaves almost exactly like render(), except you pass it the variables in can use instead of it using the current scope. This is good if you’re iterating over an array (like an array of products) and want to render each one as a template. Example:

<?php
foreach ($products as $product) {
    echo $this->partial('partials/product_row.phtml', $product);
}
?>

Conclusion

While the examples used here are specific to Zend Framework 1, the concepts are applicable to most modern frameworks and templating systems (Including Twig).

Leave a Reply