<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:py="http://genshi.edgewall.org/"
      xmlns:xi="http://www.w3.org/2001/XInclude">

  <xi:include href="header.html" />
  <xi:include href="sidebars.html" />
  <xi:include href="footer.html" />
  <xi:include href="master.html" />

<head>
  <meta content="text/html; charset=UTF-8" http-equiv="content-type" py:replace="''"/>
  <title>Learning TurboGears 2.0: Quick guide to the Quickstart pages.</title>
</head>

<body>
    ${sidebar_top()}
    ${sidebar_bottom()}
  <div id="getting_started">
    <h2>Architectural basics of a quickstart TG2 site.</h2>
    <p>The TG2 quickstart command produces this basic TG site.  Here's how it works.</p>
    <ol id="getting_started_steps">
      <li class="getting_started">
        <h3>Code your data model</h3>
        <p> There is no data model! For the quickstart site, we don't know what database you'll want to use, and in TG you can build a fairly dynamic site without any data model at all.</p>
        <p> But when you want a model for storing your favorite links or wiki content, the /model folder in your site is ready to go. .</p>
      </li>
      <li class="getting_started">
        <h3>Design your site architecture</h3>
        <p> The "<span class="code">root.py</span>" file has your URLs, all two of them.  When you called this url (<span class="code">about</span>), the command went through the RootController class to the <span class="code">about</span><span class="code">()</span> method. </p>
        <p> That method uses Python code to create a dictionary of interesting variables (in this case just "now" for the copyright date in the footer and "page" which is the name of this page, "about").</p>
        <p> Note that your URL is <span class="code">about</span>, and not "about.html".  The template (stored in /templates) is named "about.html", but the method is simply "about".  You can't get to "about.html" right now as a URL... TG2 won't let you.  That's what the Controller part of the MVC architecture is all about.</p>
      </li>
      <li class="getting_started">
        <h3>Parts of the Page</h3>
        <p> This "about" page consists of several separate templates, each one generating a part of the page.  There's a master.html, sidebars.html, header.html and footer.html in addition to the about.html template we mentioned above. We'll cover them in the order they are found, listed near the top of the about.html template</p>
        <p> <strong><span class="code">header.html</span></strong> - The "header.html" template contains the HTML code to display the blue gradient, TG2 logo, and some site text at the top of every page it is included on.  When the "about.html" template is called, it includes this "header.html" template (and the others) with a <span class="code">&lt;xi:include /&gt;</span> tag, part of the Genshi templating system.  But the "header.html" template isn't completely static HTML -- it also dynamically displays the current page name with a Genshi template method called "replace".  The code looks like this: <span class="code">&lt;span py:replace="page"/&gt;</span>, and it means: Replace this <span class="code">&lt;span /&gt;</span> with the contents found in the variable 'page' that has been sent in the dictionary to this "about.html" template, and is available through that namespace for use by this "header.html" template.  That's how it changes in the header depending on what page you are visiting.
        </p>
        <p> <strong><span class="code">sidebars.html</span></strong> - The sidebars (navigation areas on the right side of the page) are generated as two separate <span class="code">py:def</span> blocks in the "sidebars.html" template.  The <span class="code">py:def</span> construct is best thought of as a "macro" code... a simple way to separate and reuse common code snippets.  All it takes to include these on the "about.html" page template is to write  <span class="code">
<br/><br/>
    &#36; &#123;sidebar_top()&#125; 
<br/>
    &#36; &#123;sidebar_bottom()&#125;
<br/><br/>       
        </span> in the page where they are wanted.  CSS styling (in "/public/css/style.css") floats them off to the right side.  You can remove a sidebar or add more of them, and the CSS will place them one atop the other.</p>
        <p>This is, of course, also exactly how the header and footer templates are also displayed in their proper places, but we'll cover that in the "master.html" template below. (Also, there should NOT be a space between the $ sign and the curly braces, or it will not work.</p>
        <p>Oh, and in sidebar_top we've added a dynamic menu that shows the link to this page at the top when you're at the "index" page, and shows a link to the Home (index) page when you're here.  Study the "sidebars.html" template to see how we used <span class="code">py:choose</span> for that.</p>
        <p> <strong><span class="code">footer.html</span></strong> - The "footer.html" block is simple, but also utilizes a special "replace" method to set the current YEAR in the footer copyright message. The code is: <span class="code">&lt;span py:replace="now.strftime('%Y')"&gt;</span> and it uses the variable "now" that was passed in with the dictionary of variables.  But because "now" is a datetime object, we can use the Python <span class="code">"strftime()"</span> method with the "replace" call to say "Just Display The Year Here".  Simple, elegant; we format the date display in the template (the View in the Model/View/Controller architecture) rather than formatting it in the Controller method and sending it to the template as a string variable.</p>
        <p> <strong><span class="code">master.html</span></strong> - The "master.html" template is called last, by design.  The "master.html" template controls the overall design of the page we're looking at, calling first the "header" py:def macro, then the putting everything from this "about.html" template into the "main_content" div, and then calling the "footer" macro at the end.  Thus the "master.html" template provides the overall architecture for each page in this site.</p>
        <p>But why then shouldn't we call it first?  Isn't it the most important?  Perhaps, but that's precisely why we call it LAST. The "master.html" template needs to know where to find everything else, everything that it will use in py:def macros to build the page.  So that means we call the other templates first, and then call "master.html". </p>
        <p>There's more to the "master.html" template... study it to see how the &lt;title&gt; tags and static JS and CSS files are brought into the page.  Templating with Genshi is a powerful tool and we've only scratched the surface.  There are also a few little CSS tricks hidden in these pages, like the use of a "clearingdiv" to make sure that your footer stays below the sidebars and always looks right.  That's not TG2 at work, just CSS.  You'll need all your skills to build a fine web app, but TG2 will make the hard parts easier so that you can concentrate more on good design and content rather than struggling with mechanics.</p>
      </li>
    </ol>
    <p>Good luck with TurboGears 2!</p>
  </div>
</body>
</html>
