Somebody asked for some examples of how I use the
and other placeholder helpers, so I thought I'd take a crack at that today.
First off, let's look at what these helpers do. Each are concrete instances of a placeholder. In Zend Framework, placeholders are used for a number of purposes:
- Doctype awareness
- Aggregation and formatting of aggregated content
- Capturing content
- Persistence of content between view scripts and layout scripts
Let's look at these in detail.
The HTML specification encourages you to use a DocType declaration in your HTML documents — and XHTML actually requires one. Simply put, the DocType helps tell your browser what is considered valid syntax, as well as provides some hints to how it should render.
Now, if you're like me, these are a pain to remember; the syntax is somewhat
arcane, very long, and not something I want to type very often. Fortunately, the
doctype() helper allows you to use mnemonics such as
HTML4_STRICT to invoke the appropriate doctype:
<?= $this->doctype('XHTML1_TRANSITIONAL') ?>
However, a doctype isn't just a hint to the browser; it's a contract that you need to follow. If you select a particular doctype, you're agreeing to write markup that follows the specification for it.
doctype() helper is actually used internally in many of the placeholder
helpers (as well as the
form*() helpers) to ensure that the markup they
generate — if any — adheres the the given doctype. However, for this to work,
you need to specify your doctype early. I recommend doing it either in your
bootstrap or in a plugin that runs before any output is emitted; typically, I
will pull the view from the
ViewRenderer in order to do so:
$viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper('ViewRenderer'); $viewRenderer->initView(); $viewRenderer->view->doctype('XHTML1_TRANSITIONAL');
Since this sets the doctype helper's state, you can then simply echo the return value of the doctype helper later in your layout script:
<?= $this->doctype() ?>
Placeholders aggregate and store content across view instances. By aggregate, I
mean that they store the data provided in an
ArrayObject, allowing you to
collect related data for later display. Since placeholders imlement
__toString(), and can be collections, we've added accessors to allow you to
set arbitrary text to prefix, append, and separate the items in the collection.
The various concrete placeholders — primarily the
head*() helpers — make use
of this particular feature, storing each entry as a separate item in the
collection, and then decorating them when called on to render.
Additionally, the concrete instances each contain some custom logic. In the case
headScript helpers, we perform checks to ensure that when
specifying files, duplicate entries are ignored. Why is this a good idea? Well,
since you can
_forward() to other actions, or even call the
helper, you could potentially have multiple view scripts loading the same
So, as an example:
<? // /foo/bar view script: ?> <? $this->headLink()->appendStylesheet('/css/foo.css'); $this->headScript()->appendFile('/js/foo.js'); echo $this->action('baz', 'foo'); ?> <? // /foo/baz view script; ?> <? $this->headLink()->appendStylesheet('/css/foo.css'); $this->headScript()->appendFile('/js/foo.js'); ?> FOO BAZ!
It's a contrived example, for sure, but it shows the problem quite well: if two view scripts are rendered during creation of the same content, then you have the potential for duplicate content in your placeholders. However, in this case, the duplicate content will not occur, as the helpers detect the duplicate entries when they're added, and skip them.
One way in which placeholders aggregate content is by capturing content. The
base placeholder class defines both a
method, allowing you to create content in your view scripts that you then
capture for use later.
This is particularly useful for the
headScript() helper, as it allows you to
(or, if you use the
inlineScript()) helper, you can have it executed at the
end of your document, which is what Y!Slow recommends). The same goes for the
headStyle() helper; you can define custom stylesheets to include directly in
your document directly with the view that needs them.
As an example, Dojo ships with some custom stylesheets for rendering its various widgits, and also has the ability to load custom classes and widgets dynamically. Let's say we want to present a Dojo ComboBox in our page: we'll need a couple of stylesheets, as well as a few Dojo resources:
First, let's tackle the stylesheets:
<? $this->headStyle()->captureStart() ?> @import \"/js/dijit/themes/tundra/tundra.css\"; @import \"/js/dojo/resources/dojo.css\"; <? $this->headStyle()->captureEnd() ?>
These are now aggregated in our
headStyle() view helper, and we can render
them later; they will not appear inline in the page as they do here in the view
dojo.js file as a
script, and then create an inline script to load our various widgets. Dojo often
uses its own custom HTML attributes, and the
head*() helpers typically don't
like this (they like to stick to those attributes defined in the specs), so
we'll need to tell the helper that this is okay so that Dojo will parse the page
when it finishes loading (to decorate our widget with the appropriate, requested
What's the benefit to doing this? It allows you to keep the JS and CSS functionality that's related to the specific view script at hand with that view script — you have everything in one place. If you need to change what JS or CSS is loaded, or modify the inline JS you're going to utilize, you can find it with the rest of the content to which it applies.
Putting it Together: the Layout
I keep talking about "when you render it later" in this narrative. "Later" refers to your layout script. I'm not going to go into how you initialize or define your layouts here, as it's been covered in other places. However, let's look at how we can pull in our doctype and head helpers into our layout:
<?= $this->doctype() ?> <html> <head> <? // headTitle() is another concrete placeholder ?> <?= $this->headLink() ?> <?= $this->headStyle() ?> <?= $this->headScript() ?> </head> ...
Sure, you may want to put more in there than that — if you have stylesheets or scripts that load on every page, you may want to define them statically in the layout… in addition to calling the placeholder helpers. But adding the placeholder helpers gives you some definite benefits: increased separation of code, more maintainable code (as the CSS and JS specific to a view is kept with the view), simpler logic in your layouts, and the ability to prevent duplicate file inclusions.
All this functionality is now standard with Zend Framework 1.5.0; if you haven't given it a try, download it today.
Note: my colleague, Ralph Schindler — the original proposal author of
Zend_Layout and a substantial contributor to the various placeholder helpers —
is giving a webinar on Zend_Layout and Zend_View
tomorrow, 18 March 2008; if you're interested in this topic, you should check it
Updated: fixed links to layout articles.