1 <?xml version="1.0" encoding="UTF-8"?>
3 <sect1 id="zend.view.introduction">
4 <title>Introduction</title>
7 <classname>Zend_View</classname> is a class for working with the "view" portion of
8 the model-view-controller pattern. That is, it exists to
9 help keep the view script separate from the model and
10 controller scripts. It provides a system of helpers, output
11 filters, and variable escaping.
15 <classname>Zend_View</classname> is template system agnostic; you may use
16 <acronym>PHP</acronym> as your template language, or create instances of other
17 template systems and manipulate them within your view
22 Essentially, using <classname>Zend_View</classname> happens in two major steps:
23 1. Your controller script creates an instance of
24 <classname>Zend_View</classname> and assigns variables to that instance.
25 2. The controller tells the <classname>Zend_View</classname> to render a particular
26 view, thereby handing control over the view script, which
27 generates the view output.
30 <sect2 id="zend.view.introduction.controller">
31 <title>Controller Script</title>
34 As a simple example, let us say your controller has a list
35 of book data that it wants to have rendered by a view. The
36 controller script might look something like this:
39 <programlisting language="php"><![CDATA[
40 // use a model to get the data for book authors and titles.
43 'author' => 'Hernando de Soto',
44 'title' => 'The Mystery of Capitalism'
47 'author' => 'Henry Hazlitt',
48 'title' => 'Economics in One Lesson'
51 'author' => 'Milton Friedman',
52 'title' => 'Free to Choose'
56 // now assign the book data to a Zend_View instance
57 Zend_Loader::loadClass('Zend_View');
58 $view = new Zend_View();
61 // and render a view script called "booklist.php"
62 echo $view->render('booklist.php');
66 <sect2 id="zend.view.introduction.view">
67 <title>View Script</title>
70 Now we need the associated view script, "booklist.php".
71 This is a <acronym>PHP</acronym> script like any other, with one exception: it
72 executes inside the scope of the <classname>Zend_View</classname> instance, which
73 means that references to $this point to the <classname>Zend_View</classname>
74 instance properties and methods. (Variables assigned to the
75 instance by the controller are public properties of the
76 <classname>Zend_View</classname> instance). Thus, a very basic view script could
80 <programlisting language="php"><![CDATA[
83 <!-- A table of some books. -->
90 <?php foreach ($this->books as $key => $val): ?>
92 <td><?php echo $this->escape($val['author']) ?></td>
93 <td><?php echo $this->escape($val['title']) ?></td>
101 <p>There are no books to display.</p>
107 Note how we use the "escape()" method to apply output
108 escaping to variables.
112 <sect2 id="zend.view.introduction.options">
113 <title>Options</title>
116 <classname>Zend_View</classname> has several options that may be set to
117 configure the behaviour of your view scripts.
123 <property>basePath</property>: indicate a base path from which to set
124 the script, helper, and filter path. It assumes a directory
128 <programlisting language="php"><![CDATA[
136 This may be set via <methodname>setBasePath()</methodname>,
137 <methodname>addBasePath()</methodname>, or the <property>basePath</property>
138 option to the constructor.
144 <property>encoding</property>: indicate the character encoding to use
145 with <methodname>htmlentities()</methodname>,
146 <methodname>htmlspecialchars()</methodname>, and other operations. Defaults
147 to ISO-8859-1 (latin1). May be set via
148 <methodname>setEncoding()</methodname> or the <property>encoding</property>
149 option to the constructor.
155 <property>escape</property>: indicate a callback to be used by
156 <methodname>escape()</methodname>. May be set via
157 <methodname>setEscape()</methodname> or the <property>escape</property> option
164 <property>filter</property>: indicate a filter to use after rendering
165 a view script. May be set via <methodname>setFilter()</methodname>,
166 <methodname>addFilter()</methodname>, or the <property>filter</property> option
173 <property>strictVars</property>: force <classname>Zend_View</classname> to emit
174 notices and warnings when uninitialized view variables are
175 accessed. This may be set by calling
176 <methodname>strictVars(true)</methodname> or passing the
177 <property>strictVars</property> option to the constructor.
183 <sect2 id="zend.view.introduction.shortTags">
184 <title>Short Tags with View Scripts</title>
187 In our examples, we make use of <acronym>PHP</acronym> long tags:
188 <emphasis><?php</emphasis>. We also favor the use of <ulink
189 url="http://us.php.net/manual/en/control-structures.alternative-syntax.php">alternate
190 syntax for control structures</ulink>. These are convenient shorthands to use when
191 writing view scripts, as they make the constructs more terse, keep statements on single
192 lines, and eliminate the need to hunt for brackets within <acronym>HTML</acronym>.
196 In previous versions, we often recommended using short tags (<emphasis><?</emphasis>
197 and <emphasis><?=</emphasis>), as they make the view scripts slightly less verbose.
198 However, the default for the <filename>php.ini</filename>
199 <constant>short_open_tag</constant> setting is typically off in production or on shared
200 hosts -- making their use not terribly portable. If you use template
201 <acronym>XML</acronym> in view scripts, short open tags will cause the templates to fail
202 validation. Finally, if you use short tags when <constant>short_open_tag</constant> is
203 off, the view scripts will either cause errors or simply echo <acronym>PHP</acronym>
204 code back to the viewer.
208 If, despite these warnings, you wish to use short tags but they are disabled, you have
215 Turn on short tags in your <filename>.htaccess</filename> file:
218 <programlisting language="apache"><![CDATA[
219 php_value "short_open_tag" "on"
223 This will only be possible if you are allowed to create and
224 utilize <filename>.htaccess</filename> files. This directive can
225 also be added to your <filename>httpd.conf</filename> file.
231 Enable an optional stream wrapper to convert short tags to
232 long tags on the fly:
235 <programlisting language="php"><![CDATA[
236 $view->setUseStreamWrapper(true);
240 This registers <classname>Zend_View_Stream</classname> as a stream
241 wrapper for view scripts, and will ensure that your code
242 continues to work as if short tags were enabled.
248 <title>View Stream Wrapper Degrades Performance</title>
251 Usage of the stream wrapper <emphasis>will</emphasis> degrade
252 performance of your application, though actual benchmarks are
253 unavailable to quantify the amount of degradation. We recommend
254 that you either enable short tags, convert your scripts to use
255 full tags, or have a good partial and/or full page content
256 caching strategy in place.
261 <sect2 id="zend.view.introduction.accessors">
262 <title>Utility Accessors</title>
265 Typically, you'll only ever need to call on <methodname>assign()</methodname>,
266 <methodname>render()</methodname>, or one of the methods for setting/adding
267 filter, helper, and script paths. However, if you wish to extend
268 <classname>Zend_View</classname> yourself, or need access to some of its
269 internals, a number of accessors exist:
275 <methodname>getVars()</methodname> will return all assigned variables.
281 <methodname>clearVars()</methodname> will clear all assigned variables;
282 useful when you wish to re-use a view object, but want to
283 control what variables are available.
289 <methodname>getScriptPath($script)</methodname> will retrieve the
290 resolved path to a given view script.
296 <methodname>getScriptPaths()</methodname> will retrieve all registered
303 <methodname>getHelperPath($helper)</methodname> will retrieve the
304 resolved path to the named helper class.
310 <methodname>getHelperPaths()</methodname> will retrieve all registered
317 <methodname>getFilterPath($filter)</methodname> will retrieve the
318 resolved path to the named filter class.
324 <methodname>getFilterPaths()</methodname> will retrieve all registered