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> |
---|