documentation/manual/en/tutorials/layout-usage.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.layout.usage">
   4     <title>Using Zend_Layout</title>
   5
   6     <para>
   7         Basic usage of <classname>Zend_Layout</classname> is fairly trivial. Assuming you're using
   8         <classname>Zend_Application</classname> already, you can simply provide some configuration
   9         options and create a layout view script.
  10     </para>
  11
  12     <sect2 id="learning.layout.usage.configuration">
  13         <title>Layout Configuration</title>
  14
  15         <para>
  16             The recommended location of layouts is in a "<filename>layouts/scripts/</filename>"
  17             subdirectory of your application:
  18         </para>
  19
  20         <programlisting language="text"><![CDATA[
  21 application
  22 |-- Bootstrap.php
  23 |-- configs
  24 |   `-- application.ini
  25 |-- controllers
  26 |-- layouts
  27 |   `-- scripts
  28 |       |-- layout.phtml
  29 ]]></programlisting>
  30
  31         <para>
  32             To initialize <classname>Zend_Layout</classname>, add the following to your
  33             configuration file ("<filename>application/configs/application.ini</filename>"):
  34         </para>
  35
  36         <programlisting language="dosini"><![CDATA[
  37 resources.layout.layoutPath = APPLICATION_PATH "/layouts/scripts"
  38 resources.layout.layout = "layout"
  39 ]]></programlisting>
  40
  41         <para>
  42             The first line indicates where to look for layout scripts; the second line gives the
  43             name of the layout to use, minus the view script extension (which is assumed to be
  44             "<filename>.phtml</filename>" by default).
  45         </para>
  46     </sect2>
  47
  48     <sect2 id="learning.layout.usage.layout-script">
  49         <title>Create a Layout Script</title>
  50
  51         <para>
  52             Now that you have your configuration in place, you need to create your layout script.
  53             First, make sure that you've created the
  54             "<filename>application/layouts/scripts</filename>" directory; then,
  55             open an editor, and create the markup for your layout. Layout scripts are simply view
  56             scripts, with some slight differences.
  57         </para>
  58
  59         <programlisting language="php"><![CDATA[
  60 <html>
  61 <head>
  62     <title>My Site</title>
  63 </head>
  64 <body>
  65     <?php echo $this->layout()->content ?>
  66 </body>
  67 </html>
  68 ]]></programlisting>
  69
  70         <para>
  71             In the example above, you'll note the call to a <methodname>layout()</methodname> view
  72             helper. When you register the <classname>Zend_Layout</classname> resource, you also gain
  73             access to both an action and view helper that allow you access to the
  74             <classname>Zend_Layout</classname> instance; you can then call operations on the layout
  75             object. In this case, we're retrieving a named variable, <varname>$content</varname>,
  76             and echoing it. By default, the <varname>$content</varname> variable is populated for
  77             you from the application view script rendered. Otherwise, anything you'd normally do
  78             in a view script is perfectly valid -- call any helpers or view methods you desire.
  79         </para>
  80
  81         <para>
  82             At this point, you have a working layout script, and your application is informed of its
  83             location and knows to render it.
  84         </para>
  85     </sect2>
  86
  87     <sect2 id="learning.layout.usage.access">
  88         <title>Accessing the Layout Object</title>
  89
  90         <para>
  91             On occasion, you may need direct access to the layout object. There are three ways you
  92             can do this:
  93         </para>
  94
  95         <itemizedlist>
  96             <listitem>
  97                 <para>
  98                     <emphasis>Within view scripts:</emphasis> use the
  99                     <methodname>layout()</methodname> view helper, which returns the
 100                     <classname>Zend_Layout</classname> instance registered with the front controller
 101                     plugin.
 102                 </para>
 103
 104                 <programlisting language="php"><![CDATA[
 105 <?php $layout = $this->layout(); ?>
 106 ]]></programlisting>
 107
 108                 <para>
 109                     Since it returns the layout instance, you can also simply call methods on it,
 110                     rather than assigning it to a variable.
 111                 </para>
 112             </listitem>
 113
 114             <listitem>
 115                 <para>
 116                     <emphasis>Within action controllers:</emphasis> use the
 117                     <methodname>layout()</methodname> action helper, which acts just like the view
 118                     helper.
 119                 </para>
 120
 121                 <programlisting language="php"><![CDATA[
 122 // Calling helper as a method of the helper broker:
 123 $layout = $this->_helper->layout();
 124
 125 // Or, more verbosely:
 126 $helper = $this->_helper->getHelper('Layout');
 127 $layout = $helper->getLayoutInstance();
 128 ]]></programlisting>
 129
 130                 <para>
 131                     As with the view helper, since the action helper returns the layout instance,
 132                     you can also simply call methods on it, rather than assigning it to a variable.
 133                 </para>
 134             </listitem>
 135
 136             <listitem>
 137                 <para>
 138                     <emphasis>Elsewhere: </emphasis> use the static method
 139                     <methodname>getMvcInstance()</methodname>. This will return the layout instance
 140                     registered by the bootstrap resource.
 141                 </para>
 142
 143                 <programlisting language="php"><![CDATA[
 144 $layout = Zend_Layout::getMvcInstance();
 145 ]]></programlisting>
 146             </listitem>
 147
 148             <listitem>
 149                 <para>
 150                     <emphasis>Via the bootstrap: </emphasis> retrieve the layout resource, which
 151                     will be the <classname>Zend_Layout</classname> instance.
 152                 </para>
 153
 154                 <programlisting language="php"><![CDATA[
 155 $layout = $bootstrap->getResource('Layout');
 156 ]]></programlisting>
 157
 158                 <para>
 159                     Anywhere you have access to the bootstrap object, this method is preferred over
 160                     using the static <methodname>getMvcInstance()</methodname> method.
 161                 </para>
 162             </listitem>
 163         </itemizedlist>
 164     </sect2>
 165
 166     <sect2 id="learning.layout.usage.other-operations">
 167         <title>Other Operations</title>
 168
 169         <para>
 170             In most cases, the above configuration and layout script (with modifications) will get
 171             you what you need. However, some other functionality exists you will likely use sooner
 172             or later. In all of the following examples, you may use one of the <link
 173                 linkend="learning.layout.usage.access">methods listed above</link> for retrieving
 174             the layout object.
 175         </para>
 176
 177         <itemizedlist>
 178             <listitem>
 179                 <para>
 180                     <emphasis>Setting layout variables</emphasis>.
 181                     <classname>Zend_Layout</classname> keeps its own registry of layout-specific
 182                     view variables that you can access; the <varname>$content</varname> key noted in
 183                     the initial layout script sample is one such example. You can assign and
 184                     retrieve these using normal property access, or via the
 185                     <methodname>assign()</methodname> method.
 186                 </para>
 187
 188                 <programlisting language="php"><![CDATA[
 189 // Setting content:
 190 $layout->somekey = "foo"
 191
 192 // Echoing that same content:
 193 echo $layout->somekey; // 'foo'
 194
 195 // Using the assign() method:
 196 $layout->assign('someotherkey', 'bar');
 197
 198 // Access to assign()'d variables remains the same:
 199 echo $layout->someotherkey; // 'bar'
 200 ]]></programlisting>
 201             </listitem>
 202
 203             <listitem>
 204                 <para>
 205                     <methodname>disableLayout()</methodname>. Occasionally, you may want to disable
 206                     layouts; for example, when answering an Ajax request, or providing a RESTful
 207                     representation of a resource. In these cases, you can call the
 208                     <methodname>disableLayout()</methodname> method on your layout object.
 209                 </para>
 210
 211                 <programlisting language="php"><![CDATA[
 212 $layout->disableLayout();
 213 ]]></programlisting>
 214
 215                 <para>
 216                     The opposite of this method is, of course,
 217                     <methodname>enableLayout()</methodname>, which can be called at any time to
 218                     re-enable layouts for the requested action.
 219                 </para>
 220             </listitem>
 221
 222             <listitem>
 223                 <para>
 224                     <emphasis>Selecting an alternate layout</emphasis>: If you have multiple
 225                     layouts for your site or application, you can select the layout to use at any
 226                     time by simply calling the <methodname>setLayout()</methodname> method. Call it
 227                     by specifying the name of the layout script without the file suffix.
 228                 </para>
 229
 230                 <programlisting language="php"><![CDATA[
 231 // Use the layout script "alternate.phtml":
 232 $layout->setLayout('alternate');
 233 ]]></programlisting>
 234
 235                 <para>
 236                     The layout script should reside in the <varname>$layoutPath</varname> directory
 237                     specified in your configuration. <classname>Zend_Layout</classname> will then
 238                     use this new layout when rendering.
 239                 </para>
 240             </listitem>
 241         </itemizedlist>
 242     </sect2>
 243 </sect1>