Somebody asked for some examples of how I use the headLink(),
headScript(), 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.
Doctype Hinting
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 new doctype() helper allows you to use mnemonics such as
'XHTML1_TRANSITIONAL' or '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.
The 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() ?>
Content Aggregation
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 of headLink() and 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
action() view helper, you could potentially have multiple view
scripts loading the same stylesheets or javascript; we help protect against
such situations.
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.
Capturing Content
One way in which placeholders aggregate content is by capturing
content. The base placeholder class defines both a
captureStart() and captureEnd() 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 create javascript directly in your view that will be executed
in the HTML head (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 script.
Now, let's tackle the javascript. We need to load the main
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
functionality).
<? $this->
headScript() ->
setAllowArbitraryAttributes(true) ->
appendFile('/js/dojo/dojo.js',
'text/javascript',
array('djConfig' =>
'parseOnLoad: true')) ->
captureStart() ?>djConfig.usePlainJson=
true;
dojo.
require("dojo.parser");
dojo.
require("dojox.data.QueryReadStore");
dojo.
require("dijit.form.ComboBox");
<? $this->
headScript()->
captureEnd() ?>
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 out.
Updated: fixed links to layout articles.
