| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
|---|
| 2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 3 | <html xmlns="http://www.w3.org/1999/xhtml" |
|---|
| 4 | xmlns:py="http://genshi.edgewall.org/" |
|---|
| 5 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
|---|
| 6 | |
|---|
| 7 | <xi:include href="master.html" /> |
|---|
| 8 | |
|---|
| 9 | <head> |
|---|
| 10 | <meta content="text/html; charset=UTF-8" http-equiv="content-type" py:replace="''"/> |
|---|
| 11 | <title>Learning TurboGears 2.0: Quick guide to the Quickstart pages.</title> |
|---|
| 12 | </head> |
|---|
| 13 | |
|---|
| 14 | <body> |
|---|
| 15 | <div id="getting_started"> |
|---|
| 16 | <h2>Architectural basics of a quickstart TG2 site.</h2> |
|---|
| 17 | <p>The TG2 quickstart command produces this basic TG site. Here's how it works.</p> |
|---|
| 18 | <ol id="getting_started_steps"> |
|---|
| 19 | <li class="getting_started"> |
|---|
| 20 | <h3>Code my data model</h3> |
|---|
| 21 | <p> When you want a model for storing favorite links or wiki content, |
|---|
| 22 | the <strong>/model</strong> folder in your site is ready to go.</p> |
|---|
| 23 | <p> You can build a dynamic site without any data model at all. There |
|---|
| 24 | still be a default data-model template for you if you didn't enable |
|---|
| 25 | identity in quickstart. If you enable identity, you'll got |
|---|
| 26 | identity data-model made for you.</p> |
|---|
| 27 | </li> |
|---|
| 28 | <li class="getting_started"> |
|---|
| 29 | <h3>Design my URL structure</h3> |
|---|
| 30 | <p> The "<span class="code">root.py</span>" file under the |
|---|
| 31 | <strong>/controllers</strong> folder has your URLs. When you |
|---|
| 32 | called this url (<span class="code"><a href="${tg.url('/about')}">about</a></span>), |
|---|
| 33 | the command went through the RootController class to the |
|---|
| 34 | <span class="code">about</span><span class="code">()</span> method.</p> |
|---|
| 35 | <p> Those Python methods are responsible to create the dictionary of |
|---|
| 36 | variables that will be used in your web views (template).</p> |
|---|
| 37 | </li> |
|---|
| 38 | <li class="getting_started"> |
|---|
| 39 | <h3>Reuse the web page elements</h3> |
|---|
| 40 | <p> A web page viewed by user could be constructed by single or |
|---|
| 41 | several reusable templates under <strong>/templates</strong>. |
|---|
| 42 | Take 'about' page for example, each reusable templates generating |
|---|
| 43 | a part of the page. We'll cover them in the order of where they are |
|---|
| 44 | found, listed near the top of the about.html template</p> |
|---|
| 45 | <p> <strong><span class="code">header.html</span></strong> - The |
|---|
| 46 | "header.html" template contains the HTML code to display the |
|---|
| 47 | 'header': The blue gradient, TG2 logo, and some site text at the |
|---|
| 48 | top of every page it is included on. When the "about.html" template |
|---|
| 49 | is called, it includes this "header.html" template (and the others) |
|---|
| 50 | with a <span class="code"><xi:include /></span> tag, part of |
|---|
| 51 | the Genshi templating system. The "header.html" template is not a |
|---|
| 52 | completely static HTML -- it also dynamically displays the current |
|---|
| 53 | page name with a Genshi template method called "replace" with the |
|---|
| 54 | code: <span class="code"><span py:replace="page"/></span>. |
|---|
| 55 | It means replace this <span class="code"><span /></span> |
|---|
| 56 | region with the contents found in the variable 'page' that has |
|---|
| 57 | been sent in the dictionary to this "about.html" template, and is |
|---|
| 58 | available through that namespace for use by this "header.html" |
|---|
| 59 | template. That's how it changes in the header depending on what |
|---|
| 60 | page you are visiting. |
|---|
| 61 | </p> |
|---|
| 62 | <p> <strong><span class="code">sidebars.html</span></strong> - The |
|---|
| 63 | sidebars (navigation areas on the right side of the page) are |
|---|
| 64 | generated as two separate <span class="code">py:def</span> blocks |
|---|
| 65 | in the "sidebars.html" template. The <span class="code">py:def</span> |
|---|
| 66 | construct is best thought of as a "macro" code... a simple way to |
|---|
| 67 | separate and reuse common code snippets. All it takes to include |
|---|
| 68 | these on the "about.html" page template is to write |
|---|
| 69 | <span class="code"> |
|---|
| 70 | <br/><br/> |
|---|
| 71 | <br/> |
|---|
| 72 | <br/><br/> |
|---|
| 73 | </span> in the page where they are wanted. CSS styling (in |
|---|
| 74 | "/public/css/style.css") floats them off to the right side. You can |
|---|
| 75 | remove a sidebar or add more of them, and the CSS will place them one |
|---|
| 76 | atop the other.</p> |
|---|
| 77 | <p>This is, of course, also exactly how the header and footer |
|---|
| 78 | templates are also displayed in their proper places, but we'll |
|---|
| 79 | cover that in the "master.html" template below.</p> |
|---|
| 80 | <p>Oh, and in sidebar_top we've added a dynamic menu that shows the |
|---|
| 81 | link to this page at the top when you're at the "index" page, and |
|---|
| 82 | shows a link to the Home (index) page when you're here. Study the |
|---|
| 83 | "sidebars.html" template to see how we used |
|---|
| 84 | <span class="code">py:choose</span> for that.</p> |
|---|
| 85 | <p> <strong><span class="code">footer.html</span></strong> - The |
|---|
| 86 | "footer.html" block is simple, but also utilizes a special |
|---|
| 87 | "replace" method to set the current YEAR in the footer copyright |
|---|
| 88 | message. The code is: |
|---|
| 89 | <span class="code"><span py:replace="now.strftime('%Y')"> |
|---|
| 90 | </span> and it uses the variable "now" that was passed |
|---|
| 91 | in with the dictionary of variables. But because "now" is a |
|---|
| 92 | datetime object, we can use the Python |
|---|
| 93 | <span class="code">"strftime()"</span> method with the "replace" |
|---|
| 94 | call to say "Just Display The Year Here". Simple, elegant; we |
|---|
| 95 | format the date display in the template (the View in the |
|---|
| 96 | Model/View/Controller architecture) rather than formatting it in |
|---|
| 97 | the Controller method and sending it to the template as a string |
|---|
| 98 | variable.</p> |
|---|
| 99 | <p> <strong><span class="code">master.html</span></strong> - The |
|---|
| 100 | "master.html" template is called last, by design. The "master.html" |
|---|
| 101 | template controls the overall design of the page we're looking at, |
|---|
| 102 | calling first the "header" py:def macro, then the putting everything |
|---|
| 103 | from this "about.html" template into the "main_content" div, and |
|---|
| 104 | then calling the "footer" macro at the end. Thus the "master.html" |
|---|
| 105 | template provides the overall architecture for each page in this |
|---|
| 106 | site.</p> |
|---|
| 107 | <p>But why then shouldn't we call it first? Isn't it the most |
|---|
| 108 | important? Perhaps, but that's precisely why we call it LAST. |
|---|
| 109 | The "master.html" template needs to know where to find everything |
|---|
| 110 | else, everything that it will use in py:def macros to build the |
|---|
| 111 | page. So that means we call the other templates first, and then |
|---|
| 112 | call "master.html". </p> |
|---|
| 113 | <p>There's more to the "master.html" template... study it to see how |
|---|
| 114 | the <title> tags and static JS and CSS files are brought into |
|---|
| 115 | the page. Templating with Genshi is a powerful tool and we've only |
|---|
| 116 | scratched the surface. There are also a few little CSS tricks |
|---|
| 117 | hidden in these pages, like the use of a "clearingdiv" to make |
|---|
| 118 | sure that your footer stays below the sidebars and always looks |
|---|
| 119 | right. That's not TG2 at work, just CSS. You'll need all your |
|---|
| 120 | skills to build a fine web app, but TG2 will make the hard parts |
|---|
| 121 | easier so that you can concentrate more on good design and content |
|---|
| 122 | rather than struggling with mechanics.</p> |
|---|
| 123 | </li> |
|---|
| 124 | </ol> |
|---|
| 125 | <p>Good luck with TurboGears 2!</p> |
|---|
| 126 | </div> |
|---|
| 127 | </body> |
|---|
| 128 | </html> |
|---|
