Changeset 2977

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

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

Location:
documentation/trunk
Files:
4 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> 

  • documentation/trunk/topics/bloggie-stage3-skinning.dita

    r2956 r2977  
    3434      <p> 
    3535  The end result of the manipulations in this chapter is the "stage 
    36       3" Bloggie application. Inside the "stage 3" tarball you'll 
    37       find the open source Arcsin template distribution, both in an 
    38       unmodified version and pre-cut for integration with Bloggie.  
     36      3" Bloggie application. It uses the open source Blue Sky template by Arcsin, which can be obtained 
     37  from the <filepath>bluesky/</filepath> directory of this tutorial.<!-- XXX --> 
    3938      </p> 
    4039      <p>Note that Bloggie's administrative section of our "stage 3" 

  • documentation/trunk/topics/output-types.dita

    r2956 r2977  
    1616    </p> 
    1717    <section> 
    18       <title>Output Type Configuration</title> 
     18      <title>How Agavi uses the output type configuration</title> 
     19      <p>Agavi Views use the configuration items from a specific 
     20      output type. For example, you could define a "pdf" output type 
     21      that corresponds to PDF generation. The output type 
     22      configuration file allows you to specify the defaults that your 
     23      Views will use when invoked in PDF mode (e.g. Agavi 
     24      calls their <apiname>executePdf</apiname>() method).</p> 
     25      <p>Output type configuration can be used to define the following things:</p> 
     26      <dl> 
     27  <dlentry> 
     28    <dt>Layouts</dt> 
     29    <dd>A View's Layout is a list of Layers, templates and 
     30    renderers that Agavi should render after the View's 
     31    execution. Different Layouts can be configured and a View 
     32    can load any of them. You can also specify which Layout is 
     33    default in this output type.</dd> 
     34  </dlentry> 
     35  <dlentry> 
     36    <dt>Renderer configuration</dt> 
     37    <dd>Configuration parameters for Renderer classes applied 
     38    during Renderer creation in this output type. Default 
     39    Renderer class is also configurable.</dd> 
     40  </dlentry> 
     41  <dlentry> 
     42    <dt>Exception template</dt> 
     43    <dd>You can specify the emergency template that is to be 
     44    rendered if an unhandled exception occurs, substituting the 
     45    output of a failed Action.</dd> 
     46  </dlentry> 
     47  <dlentry> 
     48    <dt>HTTP headers</dt> 
     49    <dd>You can define default HTTP headers for a given output 
     50    type, so that Agavi automatically adds them to any output 
     51    generated in this output type.</dd> 
     52  </dlentry> 
     53      </dl> 
     54    </section> 
     55    <section> 
     56      <title>XML configuration example</title> 
    1957      <note type="tip">A stock Agavi application comes preconfigured 
    2058  with a default output type "html". Examine the output type 

  • documentation/trunk/tutorial.ditamap

    r2956 r2977  
    1717    <topicref href="topics/execution-flow-overview.dita"/> 
    1818    <topicref href="topics/filesystem-layout.dita"/> 
    19  
    2019    <topicref href="topics/configuration-overview.dita"/> 
    2120  </chapter> 
    … …  
    2322  <chapter href="topics/setting-up-initial-application.dita" collection-type="sequence"> 
    2423    <topicref href="topics/installing-agavi.dita"/> 
    25  
    2624    <topicref href="topics/creating-agavi-project.dita"/> 
    27  
    2825    <topicref href="topics/configuring-example-application.dita"/> 
    29  
    3026    <topicref href="topics/configuring-webserver.dita"/> 
    3127  </chapter> 
    … …  
    3329  <chapter href="topics/basics.dita" collection-type="sequence"> 
    3430    <topicref href="topics/sample-app-about.dita"/> 
    35  
    3631    <topicref href="topics/sample-app-prepare.dita"/> 
    37  
    3832    <topicref href="topics/creating-models.dita"/> 
    39  
    4033    <topicref href="topics/setting-up-actions.dita"/> 
    41  
    4234    <topicref href="topics/basics-routing.dita"/> 
    43  
    4435    <topicref href="topics/basics-running.dita"/> 
    4536  </chapter> 
    … …  
    5142      <topicref href="topics/bloggie-stage3-layout-configuration-public.dita"/> 
    5243    </topicref> 
    53 <!--    <topicref href="topics/basic-layouts.dita"> 
    54     </topicref> --> 
     44 
    5545    <topicref href="topics/basic-forms.dita"/>  
    5646    <topicref href="topics/basics-authentication-security.dita"/>