documentation/manual/en/tutorials/view-placeholders-basics.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.view.placeholders.basics">
   4     <title>Basic Placeholder Usage</title>
   5
   6     <para>
   7         Zend Framework defines a generic <methodname>placeholder()</methodname> view helper that you
   8         may use for as many custom placeholders you need. It also provides a variety of specific
   9         placeholder implementations for often-needed functionality, such as specifying the
  10         <emphasis>DocType</emphasis> declaration, document title, and more.
  11     </para>
  12
  13     <para>
  14         All placeholders operate in roughly the same way. They are containers, and thus allow you to
  15         operate on them as collections. With them you can:
  16     </para>
  17
  18     <itemizedlist>
  19         <listitem>
  20             <para>
  21                 <emphasis>Append</emphasis> or <emphasis>prepend</emphasis> items to the collection.
  22             </para>
  23         </listitem>
  24
  25         <listitem>
  26             <para>
  27                 <emphasis>Replace</emphasis> the entire collection with a single value.
  28             </para>
  29         </listitem>
  30
  31         <listitem>
  32             <para>
  33                 Specify a string with which to <emphasis>prepend output</emphasis> of the collection
  34                 when rendering.
  35             </para>
  36         </listitem>
  37
  38         <listitem>
  39             <para>
  40                 Specify a string with which to <emphasis>append output</emphasis> of the collection
  41                 when rendering.
  42             </para>
  43         </listitem>
  44
  45         <listitem>
  46             <para>
  47                 Specify a string with which to <emphasis>separate items</emphasis> of the collection
  48                 when rendering.
  49             </para>
  50         </listitem>
  51
  52         <listitem>
  53             <para>
  54                 <emphasis>Capture content</emphasis> into the collection.
  55             </para>
  56         </listitem>
  57
  58         <listitem>
  59             <para>
  60                 <emphasis>Render</emphasis> the aggregated content.
  61             </para>
  62         </listitem>
  63     </itemizedlist>
  64
  65     <para>
  66         Typically, you will call the helper with no arguments, which will return a container on
  67         which you may operate. You will then either echo this container to render it, or call
  68         methods on it to configure or populate it. If the container is empty, rendering it will
  69         simply return an empty string; otherwise, the content will be aggregated according to the
  70         rules by which you configure it.
  71     </para>
  72
  73     <para>
  74         As an example, let's create a sidebar that consists of a number of "blocks" of content.
  75         You'll likely know up-front the structure of each block; let's assume for this example that
  76         it might look like this:
  77     </para>
  78
  79     <programlisting language="html"><![CDATA[
  80 <div class="sidebar">
  81     <div class="block">
  82         <p>
  83             Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus
  84             consectetur aliquet odio ac consectetur. Nulla quis eleifend
  85             tortor. Pellentesque varius, odio quis bibendum consequat, diam
  86             lectus porttitor quam, et aliquet mauris orci eu augue.
  87         </p>
  88     </div>
  89     <div class="block">
  90         <ul>
  91             <li><a href="/some/target">Link</a></li>
  92             <li><a href="/some/target">Link</a></li>
  93         </ul>
  94     </div>
  95 </div>
  96 ]]></programlisting>
  97
  98     <para>
  99         The content will vary based on the controller and action, but the structure will be the
 100         same. Let's first setup the sidebar in a resource method of our bootstrap:
 101     </para>
 102
 103     <programlisting language="php"><![CDATA[
 104 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 105 {
 106     // ...
 107
 108     protected function _initSidebar()
 109     {
 110         $this->bootstrap('View');
 111         $view = $this->getResource('View');
 112
 113         $view->placeholder('sidebar')
 114              // "prefix" -> markup to emit once before all items in collection
 115              ->setPrefix("<div class=\"sidebar\">\n    <div class=\"block\">\n")
 116              // "separator" -> markup to emit between items in a collection
 117              ->setSeparator("</div>\n    <div class=\"block\">\n")
 118              // "postfix" -> markup to emit once after all items in a collection
 119              ->setPostfix("</div>\n</div>");
 120     }
 121
 122     // ...
 123 }
 124 ]]></programlisting>
 125
 126     <para>
 127         The above defines a placeholder, "sidebar", that has no items. It configures the basic
 128         markup structure of that placeholder, however, per our requirements.
 129     </para>
 130
 131     <para>
 132         Now, let's assume for the "user" controller that for all actions we'll want a block at the
 133         top containing some information. We could accomplish this in two ways: (a) we could add the
 134         content to the placeholder directly in the controller's
 135         <methodname>preDispatch()</methodname> method, or (b) we could render a view script from
 136         within the <methodname>preDispatch()</methodname> method. We'll use (b), as it follows a
 137         more proper separation of concerns (leaving view-related logic and functionality within a
 138         view script).
 139     </para>
 140
 141     <para>
 142         We'll name the view script "<filename>user/_sidebar.phtml</filename>", and populate it as
 143         follows:
 144     </para>
 145
 146     <programlisting language="php"><![CDATA[
 147 <?php $this->placeholder('sidebar')->captureStart() ?>
 148 <h4>User Administration</h4>
 149 <ul>
 150     <li><a href="<?php $this->url(array('action' => 'list')) ?>">
 151         List</a></li>
 152     <li><a href="<?php $this->url(array('action' => 'create')) ?>">
 153         Create</a></a></li>
 154 </ul>
 155 <?php $this->placeholder('sidebar')->captureEnd() ?>
 156 ]]></programlisting>
 157
 158     <para>
 159         The above example makes use of the content capturing feature of placeholders. By default,
 160         content is appended as a new item in the container, allowing us to aggregate content. This
 161         example makes use of view helpers and static <acronym>HTML</acronym> in order to generate
 162         markup, and the content is then captured and appended into the placeholder itself.
 163     </para>
 164
 165     <para>
 166         To invoke the above view script, we would write the following in our
 167         <methodname>preDispatch()</methodname> method:
 168     </para>
 169
 170     <programlisting language="php"><![CDATA[
 171 class UserController extends Zend_Controller_Action
 172 {
 173     // ...
 174
 175     public function preDispatch()
 176     {
 177         // ...
 178
 179         $this->view->render('user/_sidebar.phtml');
 180
 181         // ...
 182     }
 183
 184     // ...
 185 }
 186 ]]></programlisting>
 187
 188     <para>
 189         Note that we're not capturing the rendered value; there's no need, as the entierty of that
 190         view is being captured into a placeholder.
 191     </para>
 192
 193     <para>
 194         Now, let's assume our "view" action in that same controller needs to present some
 195         information. Within the "<filename>user/view.phtml</filename>" view script, we might have
 196         the following snippet of content:
 197     </para>
 198
 199     <programlisting language="php"><![CDATA[
 200 $this->placeholder('sidebar')
 201      ->append('<p>User: ' . $this->escape($this->username) .  '</p>');
 202 ]]></programlisting>
 203
 204     <para>
 205         This example makes use of the <methodname>append()</methodname> method, and passes it some
 206         simple markup to aggregate.
 207     </para>
 208
 209     <para>
 210         Finally, let's modify our layout view script, and have it render the placeholder.
 211     </para>
 212
 213     <programlisting language="php"><![CDATA[
 214 <html>
 215 <head>
 216     <title>My Site</title>
 217 </head>
 218 <body>
 219     <div class="content">
 220         <?php echo $this->layout()->content ?>
 221     </div>
 222     <?php echo $this->placeholder('sidebar') ?>
 223 </body>
 224 </html>
 225 ]]></programlisting>
 226
 227     <para>
 228         For controllers and actions that do not populate the "sidebar" placeholder, no content will
 229         be rendered; for those that do, however, echoing the placeholder will render the content
 230         according to the rules we created in our bootstrap, and the content we aggregated throughout
 231         the application. In the case of the "<filename>/user/view</filename>" action, and assuming a
 232         username of "matthew", we would get content for the sidebar as follows (formatted for
 233         readability):
 234     </para>
 235
 236     <programlisting language="html"><![CDATA[
 237 <div class="sidebar">
 238     <div class="block">
 239         <h4>User Administration</h4>
 240         <ul>
 241             <li><a href="/user/list">List</a></li>
 242             <li><a href="/user/create">Create</a></a></li>
 243         </ul>
 244     </div>
 245     <div class="block">
 246         <p>User: matthew</p>
 247     </div>
 248 </div>
 249 ]]></programlisting>
 250
 251     <para>
 252         There are a large number of things you can do by combining placeholders and layout scripts;
 253         experiment with them, and read the <link
 254             linkend="zend.view.helpers.initial.placeholder">relevant manual sections</link> for more
 255         information.
 256     </para>
 257 </sect1>