1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.layout.quickstart">
<title>Zend_Layout Quick Start</title>
<para>
There are two primary use cases for <classname>Zend_Layout</classname>: with the
Zend Framework <acronym>MVC</acronym>, and without.
</para>
<sect2 id="zend.layout.quickstart.layouts">
<title>Layout scripts</title>
<para>
In both cases, however, you'll need to create a layout script. Layout scripts simply
utilize <classname>Zend_View</classname> (or whatever view implementation you are
using). Layout variables are registered with a <classname>Zend_Layout</classname> <link
linkend="zend.view.helpers.initial.placeholder">placeholder</link>,
and may be accessed via the placeholder helper or by fetching them
as object properties of the layout object via the layout helper.
</para>
<para>
As an example:
</para>
<programlisting language="php"><![CDATA[
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>My Site</title>
</head>
<body>
<?php
// fetch 'content' key using layout helper:
echo $this->layout()->content;
// fetch 'foo' key using placeholder helper:
echo $this->placeholder('Zend_Layout')->foo;
// fetch layout object and retrieve various keys from it:
$layout = $this->layout();
echo $layout->bar;
echo $layout->baz;
?>
</body>
</html>
]]></programlisting>
<para>
Because <classname>Zend_Layout</classname> utilizes <classname>Zend_View</classname> for
rendering, you can also use any view helpers registered, and also
have access to any previously assigned view variables. Particularly
useful are the various <link
linkend="zend.view.helpers.initial.placeholder">placeholder
helpers</link>, as they allow you to
retrieve content for areas such as the <head> section,
navigation, etc.:
</para>
<programlisting language="php"><![CDATA[
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<?php echo $this->headTitle() ?>
<?php echo $this->headScript() ?>
<?php echo $this->headStyle() ?>
</head>
<body>
<?php echo $this->render('header.phtml') ?>
<div id="nav"><?php echo $this->placeholder('nav') ?></div>
<div id="content"><?php echo $this->layout()->content ?></div>
<?php echo $this->render('footer.phtml') ?>
</body>
</html>
]]></programlisting>
</sect2>
<sect2 id="zend.layout.quickstart.mvc">
<title>Using Zend_Layout with the Zend Framework MVC</title>
<para>
<classname>Zend_Controller</classname> offers a rich set of functionality for
extension via its <link linkend="zend.controller.plugins">front
controller plugins</link> and <link
linkend="zend.controller.actionhelpers">action controller
helpers</link>. <classname>Zend_View</classname> also has <link
linkend="zend.view.helpers">helpers</link>. <classname>Zend_Layout</classname>
takes advantage of these various extension points when used with the
<acronym>MVC</acronym> components.
</para>
<para>
<methodname>Zend_Layout::startMvc()</methodname> creates an instance of
<classname>Zend_Layout</classname> with any optional configuration you provide
it. It then registers a front controller plugin that renders the
layout with any application content once the dispatch loop is done,
and registers an action helper to allow access to the layout object
from your action controllers. Additionally, you may at any time grab
the layout instance from within a view script using the
<classname>Layout</classname> view helper.
</para>
<para>
First, let's look at how to initialize <classname>Zend_Layout</classname> for use with
the <acronym>MVC</acronym>:
</para>
<programlisting language="php"><![CDATA[
// In your bootstrap:
Zend_Layout::startMvc();
]]></programlisting>
<para>
<methodname>startMvc()</methodname> can take an optional array of options or
<classname>Zend_Config</classname> object to customize the instance; these
options are detailed in <link linkend="zend.layout.options">this section</link>.
</para>
<para>
In an action controller, you may then access the layout instance as
an action helper:
</para>
<programlisting language="php"><![CDATA[
class FooController extends Zend_Controller_Action
{
public function barAction()
{
// disable layouts for this action:
$this->_helper->layout->disableLayout();
}
public function bazAction()
{
// use different layout script with this action:
$this->_helper->layout->setLayout('foobaz');
};
}
]]></programlisting>
<para>
In your view scripts, you can then access the layout object via the
<classname>Layout</classname> view helper. This view helper is slightly
different than others in that it takes no arguments, and returns an
object instead of a string value. This allows you to immediately
call methods on the layout object:
</para>
<programlisting language="php"><![CDATA[
<?php $this->layout()->setLayout('foo'); // set alternate layout ?>
]]></programlisting>
<para>
At any time, you can fetch the <classname>Zend_Layout</classname> instance
registered with the <acronym>MVC</acronym> via the
<methodname>getMvcInstance()</methodname> static method:
</para>
<programlisting language="php"><![CDATA[
// Returns null if startMvc() has not first been called
$layout = Zend_Layout::getMvcInstance();
]]></programlisting>
<para>
Finally, <classname>Zend_Layout</classname>'s front controller plugin has one
important feature in addition to rendering the layout: it retrieves
all named segments from the response object and assigns them as
layout variables, assigning the 'default' segment to the variable
'content'. This allows you to access your application content and
render it in your view scripts.
</para>
<para>
As an example, let's say your code first hits
<methodname>FooController::indexAction()</methodname>, which renders some
content to the default response segment, and then forwards to
<methodname>NavController::menuAction()</methodname>, which renders content to
the 'nav' response segment. Finally, you forward to
<methodname>CommentController::fetchAction()</methodname> and fetch some
comments, but render those to the default response segment as well
(which appends content to that segment). Your view script could then
render each separately:
</para>
<programlisting language="php"><![CDATA[
<body>
<!-- renders /nav/menu -->
<div id="nav"><?php echo $this->layout()->nav ?></div>
<!-- renders /foo/index + /comment/fetch -->
<div id="content"><?php echo $this->layout()->content ?></div>
</body>
]]></programlisting>
<para>
This feature is particularly useful when used in conjunction with
the ActionStack <link linkend="zend.controller.actionhelpers.actionstack">action
helper</link> and <link
linkend="zend.controller.plugins.standard.actionstack">plugin</link>,
which you can use to setup a stack of actions through
which to loop, and thus create widgetized pages.
</para>
</sect2>
<sect2 id="zend.layout.quickstart.standalone">
<title>Using Zend_Layout as a Standalone Component</title>
<para>
As a standalone component, <classname>Zend_Layout</classname> does not offer nearly as
many features or as much convenience as when used with the <acronym>MVC</acronym>.
However, it still has two chief benefits:
</para>
<itemizedlist>
<listitem><para>Scoping of layout variables.</para></listitem>
<listitem>
<para>Isolation of layout view script from other view scripts.</para>
</listitem>
</itemizedlist>
<para>
When used as a standalone component, simply instantiate the layout
object, use the various accessors to set state, set variables as
object properties, and render the layout:
</para>
<programlisting language="php"><![CDATA[
$layout = new Zend_Layout();
// Set a layout script path:
$layout->setLayoutPath('/path/to/layouts');
// set some variables:
$layout->content = $content;
$layout->nav = $nav;
// choose a different layout script:
$layout->setLayout('foo');
// render final layout
echo $layout->render();
]]></programlisting>
</sect2>
<sect2 id="zend.layout.quickstart.example">
<title>Sample Layout</title>
<para>
Sometimes a picture is worth a thousand words. The following is a
sample layout script showing how it might all come together.
</para>
<para>
<inlinegraphic align="center" valign="middle"
fileref="figures/zend.layout.quickstart.example.png" format="PNG" />
</para>
<para>
The actual order of elements may vary, depending on the <acronym>CSS</acronym> you've
setup; for instance, if you're using absolute positioning, you may
be able to have the navigation displayed later in the document, but
still show up at the top; the same could be said for the sidebar or
header. The actual mechanics of pulling the content remain the same,
however.
</para>
</sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->
|
