Basic usage of
Zend_Layout is fairly trivial. Assuming you're using
Zend_Application already, you can simply provide some configuration
options and create a layout view script.
The recommended location of layouts is in a "
subdirectory of your application:
| `-- application.ini
| `-- scripts
| |-- layout.phtml
Zend_Layout, add the following to your
configuration file ("
resources.layout.layoutPath = APPLICATION_PATH "/layouts/scripts"
resources.layout.layout = "layout"
The first line indicates where to look for layout scripts; the second line gives the
name of the layout to use, minus the view script extension (which is assumed to be
.phtml" by default).
Now that you have your configuration in place, you need to create your layout script.
First, make sure that you've created the
application/layouts/scripts" directory; then,
open an editor, and create the markup for your layout. Layout scripts are simply view
scripts, with some slight differences.
<?php echo $this->layout()->content ?>
In the example above, you'll note the call to a
helper. When you register the
Zend_Layout resource, you also gain
access to both an action and view helper that allow you access to the
Zend_Layout instance; you can then call operations on the layout
object. In this case, we're retrieving a named variable,
and echoing it. By default, the
$content variable is populated for
you from the application view script rendered. Otherwise, anything you'd normally do
in a view script is perfectly valid -- call any helpers or view methods you desire.
At this point, you have a working layout script, and your application is informed of its location and knows to render it.
On occasion, you may need direct access to the layout object. There are three ways you can do this:
Within view scripts: use the
layout() view helper, which returns the
Zend_Layout instance registered with the front controller
<?php $layout = $this->layout(); ?>
Since it returns the layout instance, you can also simply call methods on it, rather than assigning it to a variable.
Within action controllers: use the
layout() action helper, which acts just like the view
// Calling helper as a method of the helper broker:
$layout = $this->_helper->layout();
// Or, more verbosely:
$helper = $this->_helper->getHelper('Layout');
$layout = $helper->getLayoutInstance();
As with the view helper, since the action helper returns the layout instance, you can also simply call methods on it, rather than assigning it to a variable.
Elsewhere: use the static method
getMvcInstance(). This will return the layout instance
registered by the bootstrap resource.
$layout = Zend_Layout::getMvcInstance();
Via the bootstrap: retrieve the layout resource, which
will be the
$layout = $bootstrap->getResource('Layout');
Anywhere you have access to the bootstrap object, this method is preferred over
using the static
In most cases, the above configuration and layout script (with modifications) will get you what you need. However, some other functionality exists you will likely use sooner or later. In all of the following examples, you may use one of the methods listed above for retrieving the layout object.
Setting layout variables.
Zend_Layout keeps its own registry of layout-specific
view variables that you can access; the
$content key noted in
the initial layout script sample is one such example. You can assign and
retrieve these using normal property access, or via the
// Setting content:
$layout->somekey = "foo"
// Echoing that same content:
echo $layout->somekey; // 'foo'
// Using the assign() method:
// Access to assign()'d variables remains the same:
echo $layout->someotherkey; // 'bar'
disableLayout(). Occasionally, you may want to disable
layouts; for example, when answering an Ajax request, or providing a RESTful
representation of a resource. In these cases, you can call the
disableLayout() method on your layout object.
The opposite of this method is, of course,
enableLayout(), which can be called at any time to
re-enable layouts for the requested action.
Selecting an alternate layout: If you have multiple
layouts for your site or application, you can select the layout to use at any
time by simply calling the
setLayout() method. Call it
by specifying the name of the layout script without the file suffix.
// Use the layout script "alternate.phtml":
The layout script should reside in the
specified in your configuration.
Zend_Layout will then
use this new layout when rendering.