documentation/manual/en/module_specs/Zend_View-Introduction.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.view.introduction">
   4     <title>Introduction</title>
   5
   6     <para>
   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.
  12     </para>
  13
  14     <para>
  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
  18         script.
  19     </para>
  20
  21     <para>
  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.
  28     </para>
  29
  30     <sect2 id="zend.view.introduction.controller">
  31         <title>Controller Script</title>
  32
  33         <para>
  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:
  37         </para>
  38
  39         <programlisting language="php"><![CDATA[
  40 // use a model to get the data for book authors and titles.
  41 $data = array(
  42     array(
  43         'author' => 'Hernando de Soto',
  44         'title' => 'The Mystery of Capitalism'
  45     ),
  46     array(
  47         'author' => 'Henry Hazlitt',
  48         'title' => 'Economics in One Lesson'
  49     ),
  50     array(
  51         'author' => 'Milton Friedman',
  52         'title' => 'Free to Choose'
  53     )
  54 );
  55
  56 // now assign the book data to a Zend_View instance
  57 Zend_Loader::loadClass('Zend_View');
  58 $view = new Zend_View();
  59 $view->books = $data;
  60
  61 // and render a view script called "booklist.php"
  62 echo $view->render('booklist.php');
  63 ]]></programlisting>
  64     </sect2>
  65
  66     <sect2 id="zend.view.introduction.view">
  67         <title>View Script</title>
  68
  69         <para>
  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
  77             look like this:
  78         </para>
  79
  80         <programlisting language="php"><![CDATA[
  81  if ($this->books): ?>
  82
  83     <!-- A table of some books. -->
  84     <table>
  85         <tr>
  86             <th>Author</th>
  87             <th>Title</th>
  88         </tr>
  89
  90         <?php foreach ($this->books as $key => $val): ?>
  91         <tr>
  92             <td><?php echo $this->escape($val['author']) ?></td>
  93             <td><?php echo $this->escape($val['title']) ?></td>
  94         </tr>
  95         <?php endforeach; ?>
  96
  97     </table>
  98
  99 <?php else: ?>
 100
 101     <p>There are no books to display.</p>
 102
 103 <?php endif;?>
 104 ]]></programlisting>
 105
 106         <para>
 107             Note how we use the "escape()" method to apply output
 108             escaping to variables.
 109         </para>
 110     </sect2>
 111
 112     <sect2 id="zend.view.introduction.options">
 113         <title>Options</title>
 114
 115         <para>
 116             <classname>Zend_View</classname> has several options that may be set to
 117             configure the behaviour of your view scripts.
 118         </para>
 119
 120         <itemizedlist>
 121             <listitem>
 122                 <para>
 123                     <property>basePath</property>: indicate a base path from which to set
 124                     the script, helper, and filter path. It assumes a directory
 125                     structure of:
 126                 </para>
 127
 128                 <programlisting language="php"><![CDATA[
 129 base/path/
 130     helpers/
 131     filters/
 132     scripts/
 133 ]]></programlisting>
 134
 135                 <para>
 136                     This may be set via <methodname>setBasePath()</methodname>,
 137                     <methodname>addBasePath()</methodname>, or the <property>basePath</property>
 138                     option to the constructor.
 139                 </para>
 140             </listitem>
 141
 142             <listitem>
 143                 <para>
 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.
 150                 </para>
 151             </listitem>
 152
 153             <listitem>
 154                 <para>
 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
 158                     to the constructor.
 159                 </para>
 160             </listitem>
 161
 162             <listitem>
 163                 <para>
 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
 167                     to the constructor.
 168                 </para>
 169             </listitem>
 170
 171             <listitem>
 172                 <para>
 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.
 178                 </para>
 179             </listitem>
 180         </itemizedlist>
 181     </sect2>
 182
 183     <sect2 id="zend.view.introduction.shortTags">
 184         <title>Short Tags with View Scripts</title>
 185
 186         <para>
 187             In our examples, we make use of <acronym>PHP</acronym> long tags:
 188             <emphasis>&lt;?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 HTML.
 193         </para>
 194
 195         <para>
 196             In previous versions, we often recommended using short tags (<emphasis>&lt;?</emphasis>
 197             and <emphasis>&lt;?=</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 PHP code back to the
 204             viewer.
 205         </para>
 206
 207         <para>
 208             If, despite these warnings, you wish to use short tags but they are disabled, you have
 209             two options:
 210         </para>
 211
 212         <itemizedlist>
 213             <listitem>
 214                 <para>
 215                     Turn on short tags in your <filename>.htaccess</filename> file:
 216                 </para>
 217
 218                 <programlisting language="apache"><![CDATA[
 219 php_value "short_open_tag" "on"
 220 ]]></programlisting>
 221
 222                 <para>
 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.
 226                 </para>
 227             </listitem>
 228
 229             <listitem>
 230                 <para>
 231                     Enable an optional stream wrapper to convert short tags to
 232                     long tags on the fly:
 233                 </para>
 234
 235         <programlisting language="php"><![CDATA[
 236 $view->setUseStreamWrapper(true);
 237 ]]></programlisting>
 238
 239                 <para>
 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.
 243                 </para>
 244             </listitem>
 245         </itemizedlist>
 246
 247         <warning>
 248             <title>View Stream Wrapper Degrades Performance</title>
 249
 250             <para>
 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.
 257             </para>
 258         </warning>
 259     </sect2>
 260
 261     <sect2 id="zend.view.introduction.accessors">
 262         <title>Utility Accessors</title>
 263
 264         <para>
 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:
 270         </para>
 271
 272         <itemizedlist>
 273             <listitem>
 274                 <para>
 275                     <methodname>getVars()</methodname> will return all assigned variables.
 276                 </para>
 277             </listitem>
 278
 279             <listitem>
 280                 <para>
 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.
 284                 </para>
 285             </listitem>
 286
 287             <listitem>
 288                 <para>
 289                     <methodname>getScriptPath($script)</methodname> will retrieve the
 290                     resolved path to a given view script.
 291                 </para>
 292             </listitem>
 293
 294             <listitem>
 295                 <para>
 296                     <methodname>getScriptPaths()</methodname> will retrieve all registered
 297                     script paths.
 298                 </para>
 299             </listitem>
 300
 301             <listitem>
 302                 <para>
 303                     <methodname>getHelperPath($helper)</methodname> will retrieve the
 304                     resolved path to the named helper class.
 305                 </para>
 306             </listitem>
 307
 308             <listitem>
 309                 <para>
 310                     <methodname>getHelperPaths()</methodname> will retrieve all registered
 311                     helper paths.
 312                 </para>
 313             </listitem>
 314
 315             <listitem>
 316                 <para>
 317                     <methodname>getFilterPath($filter)</methodname> will retrieve the
 318                     resolved path to the named filter class.
 319                 </para>
 320             </listitem>
 321
 322             <listitem>
 323                 <para>
 324                     <methodname>getFilterPaths()</methodname> will retrieve all registered
 325                     filter paths.
 326                 </para>
 327             </listitem>
 328         </itemizedlist>
 329     </sect2>
 330 </sect1>
 331 <!--
 332 vim:se ts=4 sw=4 et:
 333 -->