Project

General

Profile

Edit History

PageMaker » History » Version 7

Jan Klopper, 2012-05-10 10:00

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
    7
    Jan Klopper
    
To use, just subclass your PageMaker from DebuggingPageMaker:





    37
    7
    Jan Klopper
    
<pre><code class="python">





    38
    7
    Jan Klopper
    
class Minimalist(uweb.DebuggingPageMaker)





    39
    7
    Jan Klopper
    
</code></pre>





    40
    7
    Jan Klopper
    





    41
    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





    42
    3
    Elmer de Looff
    





    43
    3
    Elmer de Looff
    
In all cases, an internal server error will cause a full stacktrace to be logged in the log file database.





    44
    1
    Elmer de Looff
    





    45
    2
    Elmer de Looff
    
h1. Templateparser





    46
    1
    Elmer de Looff
    





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





    48
    2
    Elmer de Looff
    





    49
    2
    Elmer de Looff
    
<pre><code class="python">





    50
    2
    Elmer de Looff
    
import uweb





    51
    2
    Elmer de Looff
    
import time





    52
    2
    Elmer de Looff
    





    53
    5
    Elmer de Looff
    
class TemplateDemo(uweb.PageMaker):





    54
    2
    Elmer de Looff
    
  def VersionPage(self):





    55
    2
    Elmer de Looff
    
    return self.parser.Parse(





    56
    2
    Elmer de Looff
    
      'version.utp', year=time.strftime('%Y'), version=uweb.__version__)





    57
    2
    Elmer de Looff
    
</code></pre>





    58
    2
    Elmer de Looff
    





    59
    2
    Elmer de Looff
    
The example template for the above file could look something like this:





    60
    2
    Elmer de Looff
    





    61
    2
    Elmer de Looff
    
<pre><code class="html">





    62
    2
    Elmer de Looff
    
<!DOCTYPE html>





    63
    2
    Elmer de Looff
    
<html>





    64
    2
    Elmer de Looff
    
  <head>





    65
    2
    Elmer de Looff
    
    <title>µWeb version info</title>





    66
    2
    Elmer de Looff
    
  </head>





    67
    2
    Elmer de Looff
    
  <body>





    68
    2
    Elmer de Looff
    
    <p>µWeb version [version] - Copyright 2010-[year] Underdark</p>





    69
    2
    Elmer de Looff
    
  </body>





    70
    2
    Elmer de Looff
    
</html>





    71
    2
    Elmer de Looff
    
</code></pre>





    72
    2
    Elmer de Looff
    





    73
    2
    Elmer de Looff
    
And would result in the following output:





    74
    2
    Elmer de Looff
    





    75
    2
    Elmer de Looff
    
<pre><code class="html">





    76
    2
    Elmer de Looff
    
<!DOCTYPE html>





    77
    2
    Elmer de Looff
    
<html>





    78
    2
    Elmer de Looff
    
  <head>





    79
    2
    Elmer de Looff
    
    <title>µWeb version info</title>





    80
    2
    Elmer de Looff
    
  </head>





    81
    2
    Elmer de Looff
    
  <body>





    82
    2
    Elmer de Looff
    
    <p>µWeb version 0.12 - Copyright 2010-2012 Underdark</p>





    83
    2
    Elmer de Looff
    
  </body>





    84
    2
    Elmer de Looff
    
</html>





    85
    2
    Elmer de Looff
    
</code></pre>





    86
    2
    Elmer de Looff
    





    87
    2
    Elmer de Looff
    
Full documentation, with plenty of example template uses can be found on the [[TemplateParser|TemplateParser wiki-entry]].





    88
    2
    Elmer de Looff
    





    89
    2
    Elmer de Looff
    
h2. Template directory configuration





    90
    2
    Elmer de Looff
    





    91
    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/@.





    92
    2
    Elmer de Looff
    





    93
    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'@).





    94
    2
    Elmer de Looff
    





    95
    6
    Elmer de Looff
    
h1. Serving static content





    96
    1
    Elmer de Looff
    





    97
    6
    Elmer de Looff
    
Your website most likely has a few static files that need to be served up. If you have a large website you would run many of these from a separate domain (to reduce the amount of overhead from a heavy web server and complex processes), but often there are at least some files that need to be served up from the local disk.





    98
    1
    Elmer de Looff
    





    99
    6
    Elmer de Looff
    
µWeb has built-in facilities to serve static files, which prevent filesystem traversal by those lesser-behaved browsers. A browser requesting http://example.com/../secret_configuration.txt should *not* get the keys to your database server. The static handler has a base (configurable) directory from which all static content is served. For a client it is impossible to 'browse' up from that directory, preventing these leaks of information.





    100
    6
    Elmer de Looff
    





    101
    6
    Elmer de Looff
    
The MIME-Type for the content will be determined using the @mimetypes@ module (available by default in Python), based on the file's extension.





    102
    6
    Elmer de Looff
    





    103
    6
    Elmer de Looff
    
h2. Static handler demonstration





    104
    6
    Elmer de Looff
    





    105
    6
    Elmer de Looff
    
In your router configuration, add a route the directs to the static handler:





    106
    1
    Elmer de Looff
    





    107
    7
    Jan Klopper
    
<pre><code class="python">





    108
    6
    Elmer de Looff
    
ROUTES = (





    109
    6
    Elmer de Looff
    
    ...





    110
    6
    Elmer de Looff
    
    ('/images/(.*)', 'Static'),





    111
    6
    Elmer de Looff
    
    ...





    112
    6
    Elmer de Looff
    
    )





    113
    6
    Elmer de Looff
    
</code></pre>





    114
    6
    Elmer de Looff
    





    115
    6
    Elmer de Looff
    
This will cause the following behaviour:





    116
    6
    Elmer de Looff
    
* A browser requesting http://example.com/images/fish.jpg will be presented with the content from @'static/fish.jpg'@





    117
    6
    Elmer de Looff
    
* A browser requesting http://example.com/images/../../secret.txt will be presented with the content from @'static/secret.txt'@ (if it exists)





    118
    6
    Elmer de Looff
    





    119
    1
    Elmer de Looff
    
h2. Static directory configuration





    120
    1
    Elmer de Looff
    





    121
    6
    Elmer de Looff
    
As can be seen in the previous example, the content is served from the @'static'@ directory (this is not dependent on the selected route. This path is relative to the absolute path of the PageMaker itself. If the PageMaker module exists on @'/var/www/project/controller.py'@ then the default static directory is @'/var/www/project/static/'@.





    122
    1
    Elmer de Looff
    





    123
    6
    Elmer de Looff
    
This default path can be changed by setting the @PUBLIC_DIR@ class variable of PageMaker. The path can be made absolute simply by providing one:





    124
    6
    Elmer de Looff
    





    125
    6
    Elmer de Looff
    
<pre><code class="python">





    126
    6
    Elmer de Looff
    
import uweb





    127
    6
    Elmer de Looff
    





    128
    6
    Elmer de Looff
    
class DifferentPublic(uweb.PageMaker):





    129
    6
    Elmer de Looff
    
  PUBLIC_DIR = '/var/www/project/public_http'





    130
    6
    Elmer de Looff
    
</code></pre>





    131
    6
    Elmer de Looff
    





    132
    6
    Elmer de Looff
    
h2. 404 on static content





    133
    6
    Elmer de Looff
    





    134
    6
    Elmer de Looff
    
Whenever a request for static content (through @Static@) cannot be fulfilled, the method @_StaticNotFound@ is called, with the requested relative path as the sole argument. The default response for which is a simple plain text:





    135
    6
    Elmer de Looff
    





    136
    6
    Elmer de Looff
    
<pre><code class="python">





    137
    6
    Elmer de Looff
    
  def _StaticNotFound(self, _path):





    138
    6
    Elmer de Looff
    
    message = 'This is not the path you\'re looking for. No such file %r' % (





    139
    6
    Elmer de Looff
    
      self.req.env['PATH_INFO'])





    140
    6
    Elmer de Looff
    
    return response.Response(message, content_type='text/plain', httpcode=404)





    141
    6
    Elmer de Looff
    
</code></pre>





    142
    6
    Elmer de Looff
    





    143
    6
    Elmer de Looff
    
Override this page if you want to provide your user with a more informative or styled response.





    144
    6
    Elmer de Looff
    





    145
    6
    Elmer de Looff
    
h1. Login and sessions





    146
    6
    Elmer de Looff
    





    147
    6
    Elmer de Looff
    
h2. OpenID





    148
    6
    Elmer de Looff
    





    149
    6
    Elmer de Looff
    
To enable users of your website to log in using OpenID, there are only a few steps that need to be taken:





    150
    6
    Elmer de Looff
    





    151
    6
    Elmer de Looff
    
h3. Add the OpenID mixin class to PageMaker





    152
    6
    Elmer de Looff
    





    153
    6
    Elmer de Looff
    
This is as simple as adding the OpenID mixin class as one of the ancestors of your PageMaker. It is generally advisable to place mixin classes before the base class):





    154
    6
    Elmer de Looff
    





    155
    6
    Elmer de Looff
    
<pre><code class="python">





    156
    6
    Elmer de Looff
    
import uweb





    157
    6
    Elmer de Looff
    
from uweb.pagemaker import login





    158
    6
    Elmer de Looff
    





    159
    6
    Elmer de Looff
    
class Pages(login.OpenIdMixin, uweb.PageMaker):





    160
    6
    Elmer de Looff
    
</code></pre>





    161
    6
    Elmer de Looff
    





    162
    6
    Elmer de Looff
    
h3. Set up routes to the OpenID validator





    163
    6
    Elmer de Looff
    





    164
    6
    Elmer de Looff
    
The following routes (or similar ones) should be added to the [[router]]:





    165
    6
    Elmer de Looff
    





    166
    6
    Elmer de Looff
    
<pre><code class="python">





    167
    6
    Elmer de Looff
    
ROUTES = (





    168
    6
    Elmer de Looff
    
    ...





    169
    6
    Elmer de Looff
    
    ('/OpenIDLogin/?(\w+)?', '_OpenIdInitiate')





    170
    6
    Elmer de Looff
    
    ('/OpenIDValidate', '_OpenIdValidate')





    171
    6
    Elmer de Looff
    
    ...





    172
    6
    Elmer de Looff
    
    )





    173
    6
    Elmer de Looff
    
</code></pre>





    174
    6
    Elmer de Looff
    





    175
    6
    Elmer de Looff
    
The optional capture after @'OpenIDLogin'@ here is to provide the optional provider URL (instead of through the POST field @'openid_provider'@).





    176
    6
    Elmer de Looff
    





    177
    6
    Elmer de Looff
    
h3. Add handlers to PageMaker for sucess, failure, etc:





    178
    6
    Elmer de Looff
    





    179
    6
    Elmer de Looff
    
<pre><code class="python">





    180
    6
    Elmer de Looff
    
  def OpenIdAuthCancel(self, message):





    181
    6
    Elmer de Looff
    
    return 'OpenID Authentication canceled by user: %s' % message





    182
    6
    Elmer de Looff
    





    183
    6
    Elmer de Looff
    
  def OpenIdAuthFailure(self, message):





    184
    6
    Elmer de Looff
    
    return 'Authentication failed: %s' % message





    185
    6
    Elmer de Looff
    





    186
    6
    Elmer de Looff
    
  def OpenIdAuthSuccess(self, auth_dict):





    187
    6
    Elmer de Looff
    
    # Authentication succeeded, the auth_dict contains the information we received from the provider





    188
    6
    Elmer de Looff
    
    #





    189
    6
    Elmer de Looff
    
    # Next: Retrieve user information from database, or create a new user





    190
    6
    Elmer de Looff
    
    #       Store the user's session (in the database, cookie, or both)





    191
    6
    Elmer de Looff
    
    session_id = base64.urlsafe_b64encode(os.urandom(30))





    192
    6
    Elmer de Looff
    
    self.req.AddCookie('OpenIDSession', session_id, max_age=86400)





    193
    6
    Elmer de Looff
    
    return 'OpenID Authentication successful!'





    194
    6
    Elmer de Looff
    





    195
    6
    Elmer de Looff
    
  def OpenIdProviderBadLink(self, message):





    196
    6
    Elmer de Looff
    
    return 'Bad OpenID Provider URL: %s' % message





    197
    6
    Elmer de Looff
    





    198
    6
    Elmer de Looff
    
  def OpenIdProviderError(self, message):





    199
    6
    Elmer de Looff
    
    return 'The OpenID provider did not respond as expected: %r' % message





    200
    6
    Elmer de Looff
    
</code></pre>





    201
    6
    Elmer de Looff
    





    202
    6
    Elmer de Looff
    
h2. Underdark Login Framework





    203
    6
    Elmer de Looff
    





    204
    6
    Elmer de Looff
    
Using the Underdark Login Framework requires steps comparable to using OpenID, but comes with a little more default setup. The system has two modes for logging in, one that is a straightforward plaintext form submit. This is slightly easier to implement, but when used without SSL it is highly vulnerable to man-in-the-middle (MITM) attacks. The second mode is a Javascript enabled mode where the password is hashed (using the SHA-1 algorithm), and to prevent replay attacks (from a MITM), a random 'challenge' is provided for each login attempt, which is also hashed with the result. This prevents a MITM from learning the password value, or using it to log in later (though the plaintext communication remains visible).





    205
    6
    Elmer de Looff
    





    206
    6
    Elmer de Looff
    
h3. Add the ULF mixin class to PageMaker





    207
    6
    Elmer de Looff
    





    208
    6
    Elmer de Looff
    
<pre><code class="python">





    209
    6
    Elmer de Looff
    
import uweb





    210
    6
    Elmer de Looff
    
from uweb.pagemaker import login





    211
    6
    Elmer de Looff
    





    212
    6
    Elmer de Looff
    
class Pages(login.LoginMixin, uweb.PageMaker):





    213
    6
    Elmer de Looff
    
</code></pre>





    214
    6
    Elmer de Looff
    





    215
    6
    Elmer de Looff
    
h3. Set up routes to the OpenID validator





    216
    6
    Elmer de Looff
    





    217
    6
    Elmer de Looff
    
The following routes (or similar ones) should be added to the [[router]]:





    218
    6
    Elmer de Looff
    





    219
    6
    Elmer de Looff
    
<pre><code class="python">





    220
    6
    Elmer de Looff
    
ROUTES = (





    221
    6
    Elmer de Looff
    
    ...





    222
    6
    Elmer de Looff
    
    ('/ULF-Challenge', '_ULF_Challenge'),





    223
    6
    Elmer de Looff
    
    ('/ULF-Login', '_ULF_Verify'),





    224
    6
    Elmer de Looff
    
    ...





    225
    6
    Elmer de Looff
    
    )





    226
    6
    Elmer de Looff
    
</code></pre>





    227
    6
    Elmer de Looff
    





    228
    6
    Elmer de Looff
    
h3. Add handlers to PageMaker for sucess and failure:





    229
    6
    Elmer de Looff
    





    230
    6
    Elmer de Looff
    
<pre><code class="python">





    231
    6
    Elmer de Looff
    
  def _ULF_Failure(self, secure):





    232
    6
    Elmer de Looff
    
    reutrn 'ULF authentication failed (secure mode: %d)' % secure





    233
    6
    Elmer de Looff
    





    234
    6
    Elmer de Looff
    
  def _ULF_Success(self, secure):





    235
    6
    Elmer de Looff
    
    return 'ULF authentication successful! (secure mode: %d)' % secure





    236
    6
    Elmer de Looff
    
</code></pre>





    237
    2
    Elmer de Looff
    





    238
    2
    Elmer de Looff
    
h1. Persistent storage between requests





    239
    1
    Elmer de Looff
    





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





    241
    2
    Elmer de Looff
    





    242
    1
    Elmer de Looff
    
h2. Default users of the persistent storage





    243
    1
    Elmer de Looff
    





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





    245
    2
    Elmer de Looff
    





    246
    1
    Elmer de Looff
    
h2. Storing persistent values





    247
    1
    Elmer de Looff
    





    248
    1
    Elmer de Looff
    
Storing persistent values is done with the @Set@ method, as follows:





    249
    1
    Elmer de Looff
    





    250
    1
    Elmer de Looff
    
<pre><code class="python">





    251
    1
    Elmer de Looff
    
def _PostInit(self):





    252
    1
    Elmer de Looff
    
  if 'connection' not in self.persistent:





    253
    1
    Elmer de Looff
    
    self.persistent.Set('connection', self._MakeConnection())





    254
    1
    Elmer de Looff
    
</code></pre>





    255
    1
    Elmer de Looff
    





    256
    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).





    257
    2
    Elmer de Looff
    





    258
    1
    Elmer de Looff
    
h2. Retrieving persistent values





    259
    1
    Elmer de Looff
    





    260
    1
    Elmer de Looff
    
Retrieving stored values works much like this, but uses the @Get@ method:





    261
    1
    Elmer de Looff
    





    262
    1
    Elmer de Looff
    
<pre><code class="python">





    263
    1
    Elmer de Looff
    
def DatabaseAccess(self):





    264
    1
    Elmer de Looff
    
  with self.persistent.Get('connection') as cursor:





    265
    1
    Elmer de Looff
    
    cursor.Execute('INSERT INTO `message` SET `text` = "success!"')





    266
    1
    Elmer de Looff
    
</code></pre>





    267
    1
    Elmer de Looff
    





    268
    1
    Elmer de Looff
    
This uses the connection we created (or still had) during @_PostInit@, and uses it to update the database.





    269
    1
    Elmer de Looff
    





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





    271
    1
    Elmer de Looff
    





    272
    1
    Elmer de Looff
    
<pre><code class="python">





    273
    1
    Elmer de Looff
    
def FirstVisit(self):





    274
    1
    Elmer de Looff
    
  when = self.persistent.Get('first_visit_time', 'just now')





    275
    1
    Elmer de Looff
    
  return 'Your first visit was %s.' % when





    276
    1
    Elmer de Looff
    
</code></pre>





    277
    1
    Elmer de Looff
    





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





    279
    1
    Elmer de Looff
    





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





    281
    1
    Elmer de Looff
    





    282
    1
    Elmer de Looff
    
<pre><code class="python">





    283
    1
    Elmer de Looff
    
def FirstVisit(self):





    284
    1
    Elmer de Looff
    
  when = self.persistent.SetDefault('first_visit_time', datetime.datetime.now())





    285
    1
    Elmer de Looff
    
  return 'Your first visit was %s.' % when





    286
    1
    Elmer de Looff
    
</code></pre>





    287
    2
    Elmer de Looff
    





    288
    1
    Elmer de Looff
    
h2. Deleting persistent values





    289
    1
    Elmer de Looff
    





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





    291
    1
    Elmer de Looff
    





    292
    1
    Elmer de Looff
    
<pre><code class="python">





    293
    1
    Elmer de Looff
    
def DeletePersistentKey(self, key):





    294
    1
    Elmer de Looff
    
  self.persistent.Del(key)





    295
    1
    Elmer de Looff
    
</code></pre>