Project

General

Profile

PageMaker » History » Version 5

Elmer de Looff, 2012-05-07 17:41

1 3 Elmer de Looff
PageMaker is the _Controller_ of the MVC approach in µWeb. After a request is received by the web server (either [[Standalone]] or [[Apache]]) and wrapped inside a [[Request]] object, it is [[Request Router|routed]] here to be answered.
2 1 Elmer de Looff
3 3 Elmer de Looff
In the PageMaker, there might be database lookups done through the [[Model|data abstraction layer (model)]] and likely output is sent back making use of the [[TemplateParser]].
4 3 Elmer de Looff
5 3 Elmer de Looff
{{toc}}
6 3 Elmer de Looff
7 3 Elmer de Looff
h1. A very minimal PageMaker
8 3 Elmer de Looff
9 3 Elmer de Looff
In the simplest form, a PageMaker for a project subclasses from µWeb's default @PageMaker@ class and provides its own methods to handle requests. The full source for this would look something like this:
10 3 Elmer de Looff
11 3 Elmer de Looff
<pre><code class="python">
12 3 Elmer de Looff
#!/usr/bin/python
13 3 Elmer de Looff
"""PageMaker demonstration module"""
14 3 Elmer de Looff
15 3 Elmer de Looff
# uWeb framework
16 3 Elmer de Looff
import uweb
17 3 Elmer de Looff
18 5 Elmer de Looff
class Minimalist(uweb.PageMaker):
19 3 Elmer de Looff
  def Index(self):
20 3 Elmer de Looff
    return 'Welcome to our website, it is still very much under construction.'
21 3 Elmer de Looff
22 3 Elmer de Looff
  def Catchall(self, path):
23 3 Elmer de Looff
    return 'The requested page %r does not exist yet' % path
24 3 Elmer de Looff
</code></pre>
25 3 Elmer de Looff
26 1 Elmer de Looff
h1. DebuggingPageMaker
27 3 Elmer de Looff
28 3 Elmer de Looff
Before we do anything else, during development you are _strongly advised_ to use µWeb's @DebuggingPageMaker@. This has a lot of additional features for when something goes wrong on the server side. When the regular PageMaker runs into a server side error, it returns a very plain HTTP 500 response:
29 3 Elmer de Looff
30 3 Elmer de Looff
<pre>
31 3 Elmer de Looff
INTERNAL SERVER ERROR (HTTP 500) DURING PROCESSING OF '/'
32 3 Elmer de Looff
</pre>
33 3 Elmer de Looff
34 4 Elmer de Looff
Where @'/'@ is the path requested by the client. When running @DebuggingPageMaker@ there is a significantly more helpful (for the developer at least) page whenever an internal server error is encountered. It will show a full stack trace, the local variables on each stack level (typically at the point of calling another function), which helps to arrive to the point of failure more quickly.
35 4 Elmer de Looff
36 4 Elmer de Looff
Example Internal Server Error response "as image":http://bugs.underdark.nl/attachments/download/185/http500_full.png or in the "µWeb demo project":http://info.underdark.nl/haltandcatchfire?debug
37 3 Elmer de Looff
38 3 Elmer de Looff
In all cases, an internal server error will cause a full stacktrace to be logged in the log file database.
39 1 Elmer de Looff
40 2 Elmer de Looff
h1. Templateparser
41 1 Elmer de Looff
42 2 Elmer de Looff
The µWeb *[[TemplateParser]]* is available on the standard PageMaker instance. When using PageMaker, an instantiated TemplateParser instance is available through the @parser@ member of PageMaker. Basic usage looks like this:
43 2 Elmer de Looff
44 2 Elmer de Looff
<pre><code class="python">
45 2 Elmer de Looff
import uweb
46 2 Elmer de Looff
import time
47 2 Elmer de Looff
48 5 Elmer de Looff
class TemplateDemo(uweb.PageMaker):
49 2 Elmer de Looff
  def VersionPage(self):
50 2 Elmer de Looff
    return self.parser.Parse(
51 2 Elmer de Looff
      'version.utp', year=time.strftime('%Y'), version=uweb.__version__)
52 2 Elmer de Looff
</code></pre>
53 2 Elmer de Looff
54 2 Elmer de Looff
The example template for the above file could look something like this:
55 2 Elmer de Looff
56 2 Elmer de Looff
<pre><code class="html">
57 2 Elmer de Looff
<!DOCTYPE html>
58 2 Elmer de Looff
<html>
59 2 Elmer de Looff
  <head>
60 2 Elmer de Looff
    <title>µWeb version info</title>
61 2 Elmer de Looff
  </head>
62 2 Elmer de Looff
  <body>
63 2 Elmer de Looff
    <p>µWeb version [version] - Copyright 2010-[year] Underdark</p>
64 2 Elmer de Looff
  </body>
65 2 Elmer de Looff
</html>
66 2 Elmer de Looff
</code></pre>
67 2 Elmer de Looff
68 2 Elmer de Looff
And would result in the following output:
69 2 Elmer de Looff
70 2 Elmer de Looff
<pre><code class="html">
71 2 Elmer de Looff
<!DOCTYPE html>
72 2 Elmer de Looff
<html>
73 2 Elmer de Looff
  <head>
74 2 Elmer de Looff
    <title>µWeb version info</title>
75 2 Elmer de Looff
  </head>
76 2 Elmer de Looff
  <body>
77 2 Elmer de Looff
    <p>µWeb version 0.12 - Copyright 2010-2012 Underdark</p>
78 2 Elmer de Looff
  </body>
79 2 Elmer de Looff
</html>
80 2 Elmer de Looff
</code></pre>
81 2 Elmer de Looff
82 2 Elmer de Looff
Full documentation, with plenty of example template uses can be found on the [[TemplateParser|TemplateParser wiki-entry]].
83 2 Elmer de Looff
84 2 Elmer de Looff
h2. Template directory configuration
85 2 Elmer de Looff
86 2 Elmer de Looff
By default, template are loaded from the 'templates' directory that is expected to be on the same path as the pagemaker module. If your pagemaker is located on @/var/www/uweb_project/project.py@, then templates will be automatically loaded from @/var/www/uweb_project/templates/@.
87 2 Elmer de Looff
88 2 Elmer de Looff
To change the default template loading path, define a new path in the class variable @TEMPLATE_DIR@. This should be a relative path (and defaults to @'templates'@).
89 2 Elmer de Looff
90 2 Elmer de Looff
h1. Static files
91 2 Elmer de Looff
92 2 Elmer de Looff
µWeb can handle Static files from disk by itself, you just need to point the routes to the Static method, and give it the correct path where it can find the resource.
93 2 Elmer de Looff
The mime-type will be discovered automatically by using the Magic libraries avialable on your server.
94 2 Elmer de Looff
95 2 Elmer de Looff
h2. Static directory configuration
96 2 Elmer de Looff
97 2 Elmer de Looff
h1. OpenID routers
98 2 Elmer de Looff
99 2 Elmer de Looff
How to setup routes if you want to use the openID module:
100 2 Elmer de Looff
* ('/OpenIDLogin/?(\w+)?', '_OpenIdInitiate')
101 2 Elmer de Looff
* ('/OpenIDValidate', '_OpenIdValidate')
102 2 Elmer de Looff
103 2 Elmer de Looff
h1. Persistent storage between requests
104 2 Elmer de Looff
105 1 Elmer de Looff
µWeb allows you to store objects in a process-persistent storage. This means that the storage will be properly persistent and available when µWeb is in [[standalone]] mode. When running on top of [[apache]], this persistence is only as good as the apache process, which is typically a couple hundred to a few thousand requests.
106 1 Elmer de Looff
107 2 Elmer de Looff
h2. Default users of the persistent storage
108 1 Elmer de Looff
109 1 Elmer de Looff
By default, the [[TemplateParser]] and the various database connectors are stored in the persistent storage. This has the benefit that pre-parsed templates will not need to be read from disk on subsequent requests. For databases the benefit is that connections need not be made on-the-fly, but can mostly be retrieved from the storage. 
110 1 Elmer de Looff
111 2 Elmer de Looff
h2. Storing persistent values
112 1 Elmer de Looff
113 1 Elmer de Looff
Storing persistent values is done with the @Set@ method, as follows:
114 1 Elmer de Looff
115 1 Elmer de Looff
<pre><code class="python">
116 1 Elmer de Looff
def _PostInit(self):
117 1 Elmer de Looff
  if 'connection' not in self.persistent:
118 1 Elmer de Looff
    self.persistent.Set('connection', self._MakeConnection())
119 1 Elmer de Looff
</code></pre>
120 1 Elmer de Looff
121 1 Elmer de Looff
In the example above, the database connection is only created, and added to the persistent storage, if it's not already present. This way expensive but reusable actions can be optimized by performing them only once (or once every few so many requests, if running on Apache).
122 1 Elmer de Looff
123 2 Elmer de Looff
h2. Retrieving persistent values
124 1 Elmer de Looff
125 1 Elmer de Looff
Retrieving stored values works much like this, but uses the @Get@ method:
126 1 Elmer de Looff
127 1 Elmer de Looff
<pre><code class="python">
128 1 Elmer de Looff
def DatabaseAccess(self):
129 1 Elmer de Looff
  with self.persistent.Get('connection') as cursor:
130 1 Elmer de Looff
    cursor.Execute('INSERT INTO `message` SET `text` = "success!"')
131 1 Elmer de Looff
</code></pre>
132 1 Elmer de Looff
133 1 Elmer de Looff
This uses the connection we created (or still had) during @_PostInit@, and uses it to update the database.
134 1 Elmer de Looff
135 1 Elmer de Looff
In case a key has is not present in the persistent storage (because it wasn't set in the process' lifetime or because it was exlicitly dropped), the @Get@ method has an optional second argument, that is returned when the key is not present:
136 1 Elmer de Looff
137 1 Elmer de Looff
<pre><code class="python">
138 1 Elmer de Looff
def FirstVisit(self):
139 1 Elmer de Looff
  when = self.persistent.Get('first_visit_time', 'just now')
140 1 Elmer de Looff
  return 'Your first visit was %s.' % when
141 1 Elmer de Looff
</code></pre>
142 1 Elmer de Looff
143 1 Elmer de Looff
This will return the stored date and time when there was a previously recorded visit, or the text _just now_ if there was no previous time logged.
144 1 Elmer de Looff
145 1 Elmer de Looff
Finally, the persistent storage has a @SetDefault@ method, that acts much like the similarly named dictionary method. It returns the value for the given key, but if it's not present, it will set the key to the provided value, and return it as well. With this, we can improve on our first-visit tracker, and in one call retrieve or store the first time someone visited:
146 1 Elmer de Looff
147 1 Elmer de Looff
<pre><code class="python">
148 1 Elmer de Looff
def FirstVisit(self):
149 1 Elmer de Looff
  when = self.persistent.SetDefault('first_visit_time', datetime.datetime.now())
150 1 Elmer de Looff
  return 'Your first visit was %s.' % when
151 1 Elmer de Looff
</code></pre>
152 1 Elmer de Looff
153 2 Elmer de Looff
h2. Deleting persistent values
154 1 Elmer de Looff
155 1 Elmer de Looff
If for any reason you need to delete a value from the persistent storage, this can be done using the @Del@ method. The given key name is removed from the storage. *N.B.:* If the key was already removed from the storage (this can happen if the delete code runs more than once, or the key was not defined in the process' lifetime), no error is raised. It is assumed that removing the key is the only desired action.
156 1 Elmer de Looff
157 1 Elmer de Looff
<pre><code class="python">
158 1 Elmer de Looff
def DeletePersistentKey(self, key):
159 1 Elmer de Looff
  self.persistent.Del(key)
160 1 Elmer de Looff
</code></pre>