documentation/manual/en/tutorials/quickstart-create-layout.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.quickstart.create-layout">
   4     <title>Create A Layout</title>
   5
   6     <para>
   7         You may have noticed that the view scripts in the previous sections were
   8         <acronym>HTML</acronym> fragments- not complete pages. This is by design; we want our
   9         actions to return content only related to the action itself, not the application as a whole.
  10     </para>
  11
  12     <para>
  13         Now we must compose that generated content into a full <acronym>HTML</acronym> page. We'd
  14         also like to have a consistent look and feel for the application. We will use a global site
  15         layout to accomplish both of these tasks.
  16     </para>
  17
  18     <para>
  19         There are two design patterns that Zend Framework uses to implement layouts: <ulink
  20             url="http://martinfowler.com/eaaCatalog/twoStepView.html">Two Step View</ulink> and
  21         <ulink
  22             url="http://java.sun.com/blueprints/corej2eepatterns/Patterns/CompositeView.html">Composite
  23             View</ulink>. <emphasis>Two Step View</emphasis> is usually associated with the <ulink
  24             url="http://www.martinfowler.com/eaaCatalog/transformView.html">Transform View</ulink>
  25         pattern; the basic idea is that your application view creates a representation that is then
  26         injected into the master view for final transformation. The <emphasis>Composite
  27             View</emphasis> pattern deals with a view made of one or more atomic, application views.
  28     </para>
  29
  30     <para>
  31         In Zend Framework, <link linkend="zend.layout">Zend_Layout</link> combines the ideas behind
  32         these patterns. Instead of each action view script needing to include site-wide artifacts,
  33         they can simply focus on their own responsibilities.
  34     </para>
  35
  36     <para>
  37         Occasionally, however, you may need application-specific information in your site-wide view
  38         script. Fortunately, Zend Framework provides a variety of view
  39         <emphasis>placeholders</emphasis> to allow you to provide such information from your action
  40         view scripts.
  41     </para>
  42
  43     <para>
  44         To get started using <classname>Zend_Layout</classname>, first we need to inform our
  45         bootstrap to use the <classname>Layout</classname> resource. This can be done using the
  46         <command>zf enable layout</command> command:
  47     </para>
  48
  49     <programlisting language="shell"><![CDATA[
  50 % zf enable layout
  51 Layouts have been enabled, and a default layout created at
  52 application/layouts/scripts/layout.phtml
  53 A layout entry has been added to the application config file.
  54 ]]></programlisting>
  55
  56     <para>
  57         As noted by the command,
  58         <filename>application/configs/application.ini</filename> is updated, and
  59         now contains the following within the <constant>production</constant>
  60         section:
  61     </para>
  62
  63     <programlisting language="ini"><![CDATA[
  64 ; application/configs/application.ini
  65
  66 ; Add to [production] section:
  67 resources.layout.layoutPath = APPLICATION_PATH "/layouts/scripts"
  68 ]]></programlisting>
  69
  70     <para>
  71         The final <acronym>INI</acronym> file should look as follows:
  72     </para>
  73
  74     <programlisting language="ini"><![CDATA[
  75 ; application/configs/application.ini
  76
  77 [production]
  78 ; PHP settings we want to initialize
  79 phpSettings.display_startup_errors = 0
  80 phpSettings.display_errors = 0
  81 includePaths.library = APPLICATION_PATH "/../library"
  82 bootstrap.path = APPLICATION_PATH "/Bootstrap.php"
  83 bootstrap.class = "Bootstrap"
  84 appnamespace = "Application"
  85 resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"
  86 resources.frontController.params.displayExceptions = 0
  87 resources.layout.layoutPath = APPLICATION_PATH "/layouts/scripts"
  88
  89 [staging : production]
  90
  91 [testing : production]
  92 phpSettings.display_startup_errors = 1
  93 phpSettings.display_errors = 1
  94
  95 [development : production]
  96 phpSettings.display_startup_errors = 1
  97 phpSettings.display_errors = 1
  98 ]]></programlisting>
  99
 100     <para>
 101         This directive tells your application to look for layout view scripts in
 102         <filename>application/layouts/scripts</filename>. If you examine your directory tree, you'll
 103         see that this directory has been created for you now, with the file
 104         <filename>layout.phtml</filename>.
 105     </para>
 106
 107     <para>
 108         We also want to ensure we have an XHTML DocType declaration for our application. To enable
 109         this, we need to add a resource to our bootstrap.
 110     </para>
 111
 112     <para>
 113         The simplest way to add a bootstrap resource is to simply create a protected method
 114         beginning with the phrase <methodname>_init</methodname>. In this case, we want to
 115         initialize the doctype, so we'll create an <methodname>_initDoctype()</methodname> method
 116         within our bootstrap class:
 117     </para>
 118
 119     <programlisting language="php"><![CDATA[
 120 // application/Bootstrap.php
 121
 122 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 123 {
 124     protected function _initDoctype()
 125     {
 126     }
 127 }
 128 ]]></programlisting>
 129
 130     <para>
 131         Within that method, we need to hint to the view to use the appropriate doctype. But where
 132         will the view object come from? The easy solution is to initialize the
 133         <classname>View</classname> resource; once we have, we can pull the view object from the
 134         bootstrap and use it.
 135     </para>
 136
 137     <para>
 138         To initialize the view resource, add the following line to your
 139         <filename>application/configs/application.ini</filename> file, in the section marked
 140         <constant>production</constant>:
 141     </para>
 142
 143     <programlisting language="ini"><![CDATA[
 144 ; application/configs/application.ini
 145
 146 ; Add to [production] section:
 147 resources.view[] =
 148 ]]></programlisting>
 149
 150     <para>
 151         This tells us to initialize the view with no options (the '[]' indicates that the "view" key
 152         is an array, and we pass nothing to it).
 153     </para>
 154
 155     <para>
 156         Now that we have a view, let's flesh out our <methodname>_initDoctype()</methodname> method.
 157         In it, we will first ensure the <classname>View</classname> resource has run, fetch the view
 158         object, and then configure it:
 159     </para>
 160
 161     <programlisting language="php"><![CDATA[
 162 // application/Bootstrap.php
 163
 164 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 165 {
 166     protected function _initDoctype()
 167     {
 168         $this->bootstrap('view');
 169         $view = $this->getResource('view');
 170         $view->doctype('XHTML1_STRICT');
 171     }
 172 }
 173 ]]></programlisting>
 174
 175     <para>
 176         Now that we've initialized <classname>Zend_Layout</classname> and set the Doctype, let's
 177         create our site-wide layout:
 178     </para>
 179
 180     <programlisting language="php"><![CDATA[
 181 <!-- application/layouts/scripts/layout.phtml -->
 182 <?php echo $this->doctype() ?>
 183 <html xmlns="http://www.w3.org/1999/xhtml">
 184 <head>
 185   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 186   <title>Zend Framework Quickstart Application</title>
 187   <?php echo $this->headLink()->appendStylesheet('/css/global.css') ?>
 188 </head>
 189 <body>
 190 <div id="header" style="background-color: #EEEEEE; height: 30px;">
 191     <div id="header-logo" style="float: left">
 192         <b>ZF Quickstart Application</b>
 193     </div>
 194     <div id="header-navigation" style="float: right">
 195         <a href="<?php echo $this->url(
 196             array('controller'=>'guestbook'),
 197             'default',
 198             true) ?>">Guestbook</a>
 199     </div>
 200 </div>
 201
 202 <?php echo $this->layout()->content ?>
 203
 204 </body>
 205 </html>
 206 ]]></programlisting>
 207
 208     <para>
 209         We grab our application content using the <methodname>layout()</methodname> view helper, and
 210         accessing the "content" key. You may render to other response segments if you wish to, but
 211         in most cases, this is all that's necessary.
 212     </para>
 213
 214     <para>
 215         Note also the use of the <methodname>headLink()</methodname> placeholder. This is an easy
 216         way to generate the <acronym>HTML</acronym> for &lt;link&gt; elements, as well as to keep
 217         track of them throughout your application. If you need to add additional CSS sheets to
 218         support a single action, you can do so, and be assured it will be present in the final
 219         rendered page.
 220     </para>
 221
 222     <note>
 223         <title>Checkpoint</title>
 224
 225         <para>
 226             Now go to "http://localhost" and check out the source. You should see your XHTML header,
 227             head, title, and body sections.
 228         </para>
 229     </note>
 230 </sect1>