Nevow render用法（转）

<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script><script type="text/javascript"><!-- _uacct = "UA-99018-3"; urchinTracker(); // --></script>
1 Nevow Object Publishing
2 =======================
3
4 In Nevow Object Traversal, we learned about the
5 nevow.inevow.IResource.renderHTTP method, which is the most basic way to send
6 HTML to a browser when using Nevow. However, it is not very convenient (or
7 clean) to generate HTML tags by concatenating strings in Python code. In the
8 Nevow Deployment documentation, we saw that it was possible to render a Hello
9 World page using a nevow.rend.Page subclass and providing a "docFactory"::
10
11 >>> from nevow import rend, loaders
12 >>> class HelloWorld(rend.Page):
13 ... docFactory = loaders.stan("Hello, world!")
14 ...
15 >>> HelloWorld().renderSynchronously()
16 'Hello, world!'
17
18 This example does nothing interesting, but the concept of a loader is important
19 in Nevow. The rend.Page.renderHTTP implementation always starts rendering HTML
20 by loading a template from the docFactory.
21
22 * `The stan DOM`_
23 * `Tag instances`_
24 * `Functions in the DOM`_
25 * `Accessing query parameters and form post data`_
26 * `Generators in the DOM`_
27 * `Methods in the DOM`_
28 * `Data specials`_
29 * `Render specials`_
30 * `Pattern specials`_
31 * `Slot specials`_
32 * `Data directives`_
33 * `Render directives`_
34 * `Flatteners`_
35
36 The stan DOM
37 ------------
38
39 Nevow uses a DOM-based approach to rendering HTML. A tree of objects is first
40 constructed in memory by the template loader. This tree is then processed one
41 node at a time, applying functions which transform from various Python types to
42 HTML strings.
43
44 Nevow uses a nonstandard DOM named "stan". Unlike the W3C DOM, stan is made up
45 of simple python lists, strings, and instances of the nevow.stan.Tag class.
46 During the rendering process, "Flattener" functions convert from rich types to
47 HTML strings. For example, we can load a template made up of some nested lists
48 and Python types, render it, and see what happens::
49
50 >>> class PythonTypes(rend.Page):
51 ... docFactory = loaders.stan(["Hello", 1, 1.5, True, ["Goodbye", 3]])
52 ...
53 >>> PythonTypes().renderSynchronously()
54 'Hello11.5TrueGoodbye3'
55
56 Tag instances
57 -------------
58
59 So far, we have only rendered simple strings as output. However, the main
60 purpose of Nevow is HTML generation. In the stan DOM, HTML tags are represented
61 by instances of the nevow.stan.Tag class. Tag is a very simple class, whose
62 instances have an "attributes" dictionary and a "children" list. The Tag
63 flattener knows how to recursively flatten attributes and children of the tag.
64 To show you how Tags really work before you layer Nevow's convenience syntax on
65 top, try this horrible example::
66
67 >>> from nevow import stan
68 >>> h = stan.Tag('html')
69 >>> d = stan.Tag('div')
70 >>> d.attributes['style'] = 'border: 1px solid black'
71 >>> h.children.append(d)
72 >>> class Tags(rend.Page):
73 ... docFactory = loaders.stan(h)
74 ...
75 >>> Tags().renderSynchronously()
76 '<html><div style="border: 1px solid black"></div></html>'
77
78 So, we see how it is possible to programatically generate HTML by constructing
79 and nesting stan Tag instances. However, it is far more convenient to use the
80 overloaded operators Tag provides to manipulate them. Tag implements a __call__
81 method which takes any keyword arguments and values and updates the attributes
82 dictionary; it also implements a __getitem__ method which takes whatever is
83 between the square brackets and appends them to the children list. A simple
84 example should clarify things::
85
86 >>> class Tags2(rend.Page):
87 ... docFactory = loaders.stan(stan.Tag('html')[stan.Tag('div')(style="border: 1px solid black")])
88 ...
89 >>> Tags2().renderSynchronously()
90 '<html><div style="border: 1px solid black"></div></html>'
91
92 This isn't very easy to read, but luckily we can simplify the example even
93 further by using the nevow.tags module, which is full of "Tag prototypes" for
94 every tag type described by the XHTML 1.0 specification::
95
96 >>> class Tags3(rend.Page):
97 ... docFactory = loaders.stan(tags.html[tags.div(style="border: 1px solid black")])
98 ...
99 >>> Tags3().renderSynchronously()
100 '<html><div style="border: 1px solid black"></div></html>'
101
102 Using stan syntax is not the only way to construct template DOM for use by the
103 Nevow rendering process. Nevow also includes loaders.xmlfile which implements a
104 simple tag attribute language similar to the Zope Page Templates (ZPT) Tag
105 Attribute Language (TAL). However, experience with the stan DOM should give you
106 insight into how the Nevow rendering process really works. Rendering a template
107 into HTML in Nevow is really nothing more than iterating a tree of objects and
108 recursively applying "Flattener" functions to objects in this tree, until all
109 HTML has been generated.
110
111 Functions in the DOM
112 --------------------
113
114 So far, all of our examples have generated static HTML pages, which is not
115 terribly interesting when discussing dynamic web applications. Nevow takes a
116 very simple approach to dynamic HTML generation. If you put a Python function
117 reference in the DOM, Nevow will call it when the page is rendered. The return
118 value of the function replaces the function itself in the DOM, and the results
119 are flattened further. This makes it easy to express looping and branching
120 structures in Nevow, because normal Python looping and branching constructs are
121 used to do the job::
122
123 >>> def repeat(ctx, data):
124 ... return [tags.div(style="color: %s" % (color, ))
125 ... for color in ['red', 'blue', 'green']]
126 ...
127 >>> class Repeat(rend.Page):
128 ... docFactory = loaders.stan(tags.html[repeat])
129 ...
130 >>> Repeat().renderSynchronously()
131 '<html><div style="color: red"></div><div style="color: blue"></div><div style="color: green"></div></html>'
132
133 However, in the example above, the repeat function isn't even necessary, because
134 we could have inlined the list comprehension right where we placed the function
135 reference in the DOM. Things only really become interesting when we begin
136 writing parameterized render functions which cause templates to render
137 differently depending on the input to the web application.
138
139 The required signature of functions which we can place in the DOM is (ctx,
140 data). The "context" object is essentially opaque for now, and we will learn how
141 to extract useful information out of it later. The "data" object is anything we
142 want it to be, and can change during the rendering of the page. By default, the
143 data object is whatever we pass as the first argument to the Page constructor,
144 **or** the Page instance itself if nothing is passed. Armed with this knowledge,
145 we can create a Page which renders differently depending on the data we pass to
146 the Page constructor::
147
148 class Root(rend.Page):
149 docFactory = loaders.stan(tags.html[
150 tags.h1["Welcome."],
151 tags.a(href="foo")["Foo"],
152 tags.a(href="bar")["Bar"],
153 tags.a(href="baz")["Baz"]])
154
155 def childFactory(self, ctx, name):
156 return Leaf(name)
157
158
159 def greet(ctx, name):
160 return "Hello. You are visiting the ", name, " page."
161
162 class Leaf(rend.Page):
163 docFactory = loaders.stan(tags.html[greet])
164
165 Armed with this knowledge and the information in the Object Traversal
166 documentation, we now have enough information to create dynamic websites with
167 arbitrary URL hierarchies whose pages render dynamically depending on which URL
168 was used to access them.
169
170 Accessing query parameters and form post data
171 ---------------------------------------------
172
173 Before we move on to more advanced rendering techniques, let us first examine
174 how one could further customize the rendering of a Page based on the URL query
175 parameters and form post information provided to us by a browser. Recall that
176 URL parameters are expressed in the form::
177
178 http://example.com/foo/bar?baz=1&quux=2
179
180 And form post data can be generated by providing a form to a browser::
181
182 <form action="" method="POST">
183 <input type="text" name="baz" />
184 <input type="text" name="quux" />
185 <input type="submit" />
186 </form>
187
188 Accessing this information is such a common procedure that Nevow provides a
189 convenience method on the context to do it. Let's examine a simple page whose
190 output can be influenced by the query parameters in the URL used to access it::
191
192 def showChoice(ctx, data):
193 choice = ctx.arg('choice')
194 if choice is None:
195 return ''
196 return "You chose ", choice, "."
197
198 class Custom(rend.Page):
199 docFactory = loaders.stan(tags.html[
200 tags.a(href="?choice=baz")["Baz"],
201 tags.a(href="?choice=quux")["Quux"],
202 tags.p[showChoice]])
203
204 The procedure is exactly the same for simple form post information::
205
206 def greet(ctx, data):
207 name = ctx.arg('name')
208 if name is None:
209 return ''
210 return "Greetings, ", name, "!"
211
212 class Form(rend.Page):
213 docFactory = loaders.stan(tags.html[
214 tags.form(action="", method="POST")[
215 tags.input(name="name"),
216 tags.input(type="submit")],
217 greet])
218
219 Note that ctx.arg returns only the first argument with the given name. For
220 complex cases where multiple arguments and lists of argument values are
221 required, you can access the request argument dictionary directly using the
222 syntax::
223
224 def arguments(ctx, data):
225 args = inevow.IRequest(ctx).args
226 return "Request arguments are: ", str(args)
227
228 Generators in the DOM
229 ---------------------
230
231 One common operation when building dynamic pages is iterating a list of data and
232 emitting some HTML for each item. Python generators are well suited for
233 expressing this sort of logic, and code which is written as a python generator
234 can perform tests (if) and loops of various kinds (while, for) and emit a row of
235 html whenever it has enough data to do so. Nevow can handle generators in the
236 DOM just as gracefully as it can handle anything else::
237
238 >>> from nevow import rend, loaders, tags
239 >>> def generate(ctx, items):
240 ... for item in items:
241 ... yield tags.div[ item ]
242 ...
243 >>> class List(rend.Page):
244 ... docFactory = loaders.stan(tags.html[ generate ])
245 ...
246 >>> List(['one', 'two', 'three']).renderSynchronously()
247 '<html><div>one</div><div>two</div><div>three</div></html>'
248
249 As you can see, generating HTML inside of functions or generators can be very
250 convenient, and can lead to very rapid application development. However, it is
251 also what I would call a "template abstraction violation", and we will learn how
252 we can keep knowledge of HTML out of our python code when we learn about
253 patterns and slots.
254
255 Methods in the DOM
256 ------------------
257
258 Up until now, we have been placing our template manipulation logic inside of
259 simple Python functions and generators. However, it is often appropriate to use
260 a method instead of a function. Nevow makes it just as easy to use a method to
261 render HTML::
262
263 class MethodRender(rend.Page):
264 def __init__(self, foo):
265 self.foo = foo
266
267 def render_foo(self, ctx, data):
268 return self.foo
269
270 docFactory = loaders.stan(tags.html[ render_foo ])
271
272 Using render methods makes it possible to parameterize your Page class with more
273 parameters. With render methods, you can also use the Page instance as a state
274 machine to keep track of the state of the render. While Nevow is designed to
275 allow you to render the same Page instance repeatedly, it can also be convenient
276 to know that a Page instance will only be used one time, and that the Page
277 instance can be used as a scratch pad to manage information about the render.
278
279 Data specials
280 -------------
281
282 Previously we saw how passing a parameter to the default Page constructor makes
283 it available as the "data" parameter to all of our render methods. This "data"
284 parameter can change as the page render proceeds, and is a useful way to ensure
285 that render functions are isolated and only act upon the data which is available
286 to them. Render functions which do not pull information from sources other than
287 the "data" parameter are more easily reusable and can be composed into larger
288 parts more easily.
289
290 Deciding which data gets passed as the data parameter is as simple as changing
291 the "Data special" for a Tag. See the Glossary under "Tag Specials" for more
292 information about specials. Assigning to the data special is as simple as
293 assigning to a tag attribute::
294
295 >>> def hello(ctx, name):
296 ... return "Hello, ", name
297 ...
298 >>> class DataSpecial(rend.Page):
299 ... docFactory = loaders.stan(tags.html[
300 ... tags.div(data="foo")[ hello ],
301 ... tags.div(data="bar")[ hello ]])
302 ...
303 >>> DataSpecial().renderSynchronously()
304 '<html><div>Hello, foo</div><div>Hello, bar</div></html>'
305
306 Data specials may be assigned any python value. Data specials are only in scope
307 during the rendering of the tag they are assigned to, so if the "hello" renderer
308 were placed in the DOM inside the html node directly, "Hello, None" would be
309 output.
310
311 Before data is passed to a render function, Nevow first checks to see if there
312 is an IGettable adapter for it. If there is, it calls IGettable.get(), and
313 passes the result of this as the data parameter instead. Nevow includes an
314 IGettable adapter for python functions, which means you can set a Tag data
315 special to a function reference and Nevow will call it to obtain the data when
316 the Tag is rendered. The signature for data methods is similar to that of render
317 methods, (ctx, data). For example::
318
319 def getName(ctx, data):
320 return ctx.arg('name')
321
322 def greet(ctx, name):
323 return "Greetings, ", name
324
325 class GreetName(rend.Page):
326 docFactory = loaders.stan(tags.html[
327 tags.form(action="")[
328 tags.input(name="name"),
329 tags.input(type="submit")],
330 tags.div(data=getName)[ greet ]])
331
332 Data specials exist mainly to allow you to construct and enforce a
333 Model-View-Controller style separation of the Model code from the View. Here we
334 see that the greet function is capable of rendering a greeting view for a name
335 model, and that the implementation of getName may change without the view code
336 changing.
337
338 Render specials
339 ---------------
340
341 Previously, we have seen how render functions can be placed directly in the DOM,
342 and the return value replaces the render function in the DOM. However, these
343 free functions and methods are devoid of any contextual information about the
344 template they are living in. The render special is a way to associate a render
345 function or method with a particular Tag instance, which the render function can
346 then examine to decide how to render::
347
348 >>> def alignment(ctx, data):
349 ... align = ctx.tag.attributes.get('align')
350 ... if align == 'right':
351 ... return ctx.tag["Aligned right"]
352 ... elif align == 'center':
353 ... return ctx.tag["Aligned center"]
354 ... else:
355 ... return ctx.tag["Aligned left"]
356 ...
357 >>> class AlignmentPage(rend.Page):
358 ... docFactory = loaders.stan(tags.html[
359 ... tags.p(render=alignment),