Show
Ignore:
Timestamp:
10/04/08 16:51:32 (3 months ago)
Author:
mikeseth
Message:

final shape for the skinning chapter: now needs rest of examples & polish

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • documentation/trunk/topics/bloggie-stage3-layout-configuration-public.dita

    r2956 r2977  
    55  <title>Configuring Bloggie layouts</title> 
    66  <body> 
    7     <p>In order to dress Bloggie using the open source Arcsin template, we need to complete a number of steps: 
     7    <p>In order to dress Bloggie using a given template, we need to perform several steps: 
    88      <ol> 
    99  <li>Cut out and adjust the decorator template for all our Views and place it in the template directory</li> 
    … …  
    1313      </ol> 
    1414    </p> 
     15    <p>Once configured, Agavi's rendering mechanism will apply the 
     16    templates in the proper order, and we'll be able to see our 
     17    Bloggie application dressed.</p> 
    1518    <section> 
    1619      <title>Preparing the template</title> 
    17       <p> 
    18       </p> 
     20      <p>For the purposes of this example application, we'll be using 
     21  the open source Blue Sky template by Arcsin. It is a simple 
     22      template that has a single template layout contained in <filepath>index.html</filepath>, a stylesheet and a couple of images.</p> 
     23      <p>First, let's copy the contents 
     24      of <filepath>index.html</filepath> to the application. Since 
     25      we're dressing a single <keyword>Module</keyword>, we'll create 
     26      the decorator template 
     27      in <filepath>app/modules/Public/templates/decorator.php</filepath></p> 
     28      <p>Now we have to make some edits in the original Blue Sky 
     29      layout to make it an appropriate decorator template.</p> 
     30      <p>First, we need to let the browsers know how to calculate 
     31      relative paths: you will see the HTML BASE element in this 
     32      template receiving its base value from Agavi's Routing. This is 
     33      a good practice.</p> 
     34      <p>Second, we need to remove all the "inner" content of the 
     35      decorator that our Actions will be filling. To substitute the 
     36      output, we use a special variable <varname>$inner</varname>.</p> 
     37      <p>We also need to copy the template's resources (images and the 
     38      stylesheet) to our <filepath>pub/</filepath> directory so that 
     39      they become available to the webserver. Since these all belong 
     40      to the Public <keyword>Module</keyword>, we'll create a subdirectory and copy everything template related in it:</p> 
     41      <ul> 
     42  <li><filepath>pub/public/default.css</filepath></li> 
     43  <li><filepath>pub/public/img/bgcode.gif</filepath></li> 
     44  <li><filepath>pub/public/img/bg.gif</filepath></li> 
     45  <li><filepath>pub/public/img/bgholder.jpg</filepath></li> 
     46  <li><filepath>pub/public/img/holder.jpg</filepath></li> 
     47  <li><filepath>pub/public/img/li.gif</filepath></li> 
     48  <li><filepath>pub/public/img/navhover.gif</filepath></li> 
     49  <li><filepath>pub/public/img/quote.gif</filepath></li> 
     50      </ul> 
     51      <p>Since we added a subdirectory for the module, we'll also need 
     52  to adjust paths in the stylesheet and the decorator to point 
     53  to the new locations of the image files.</p> 
     54      <p>The resulting <filepath>decorator.php</filepath> will now 
     55      look like this:</p> 
     56      <p>(example)</p> 
     57      <p>Now we need to remove the HTML header and footer from the 
     58      Action templates, because these will be provided by the decorator. Here's new code for both of our Actions:</p> 
     59      <p>(example)</p> 
    1960    </section> 
    2061    <section> 
    2162      <title>Configuring Bloggie to use the new decorator</title> 
    22       <p> 
     63      <p>Reconfiguring Bloggie in our case is very simple: we need to 
     64      add another Layer into the default layout for HTML output 
     65      type. Here's the changed file: 
    2366      </p> 
     67      <p>(example)</p> 
     68      <p>The View can create the layout from scratch using Agavi API, 
     69      or load a desired layout from the configuration. The layout configuration is then used by Agavi to perform rendering.</p> 
     70      <p>In our case, the following will happen in a View with our new configuration:</p> 
     71      <ol> 
     72  <li>The View's executeHtml() calls setupHtml()</li> 
     73  <li>setupHtml() loads the specified layout, or a default for this output type</li> 
     74  <li>The loaded layout defines two Layers with associated PHP 
     75  renderers. The top layer is for the output of this Action, and 
     76  the bottom one is for the decorator. The template file name 
     77  for the top layer is derived from the View's name. The 
     78  template file name for the bottom layer is fixed in the 
     79  configuration.</li> 
     80  <li>The View does whatever setup is needed for this particular View/template and finishes</li> 
     81  <li>Agavi grabs the layout and processes the layers 
     82  sequentially. The View's template in the top layer is rendered 
     83  and exported into the next iteration. Then, the bottom layer's 
     84  fixed decorator template is rendered, and the rendered result of the previous layer is inserted using <varname>$inner</varname></li> 
     85  <li>When the rendering process finishes, the last collected 
     86  output becomes the body of the Action's response.</li> 
     87      </ol> 
     88      <p>Voila! Now Bloggie has a complete look.</p> 
    2489    </section> 
    2590  </body>