document and make easier the actions-returning-content idiom

Author: Richard Jones

CHANGES.txt

@@ -30,6 +30,8 @@ Feature:
 - HTMLLinkProperty field() method renders as a field now (thanks darryl)
 - all HTML templating methods now automatically check for permissions
   (either view or edit as appropriate), greatly simplifying templates
+- cgi Action handlers may now return the actual content to be sent back to
+  the user (rather than using some template)
 
 Fixed:
 - mysql documentation fixed to note requirement of 4.0+ and InnoDB

doc/customizing.txt

@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.116 $
+:Version: $Revision: 1.117 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -2148,6 +2148,23 @@ In your HTML form, add a hidden form element like so::
 
 where "myaction" is the name you registered in the previous step.
 
+Actions may return content to the user
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Actions generally perform some database manipulation and then pass control
+on to the rendering of a template in the current context (see `Determining
+web context`_ for how that works.) Some actions will want to generate the
+actual content returned to the user. Action methods may return their own
+content string to be displayed to the user, overriding the templating step.
+In this situation, we assume that the content is HTML by default. You may
+override the content type indicated to the user by calling ``setHeader``::
+
+   self.client.setHeader('Content-Type', 'text/csv')
+
+This example indicates that the value sent back to the user is actually
+comma-separated value content (eg. something to be loaded into a
+spreadsheet or database).
+
 
 Examples
 ========

roundup/cgi/client.py

@@ -1,4 +1,4 @@
-# $Id: client.py,v 1.163 2004-02-25 03:24:43 richard Exp $
+# $Id: client.py,v 1.164 2004-02-25 03:39:53 richard Exp $
 
 """WWW request handler (also used in the stand-alone server).
 """
@@ -249,24 +249,18 @@ def clean_sessions(self):
         Note: also cleans One Time Keys, and other "session" based stuff.
         """
         sessions = self.db.sessions
-        last_clean = sessions.get('last_clean', 'last_use') or 0
+        last_clean = self.db.sessions.get('last_clean', 'last_use') or 0
 
+        # time to clean?
         week = 60*60*24*7
         hour = 60*60
         now = time.time()
-        if now - last_clean > hour:
-            # remove aged sessions
-            for sessid in sessions.list():
-                interval = now - sessions.get(sessid, 'last_use')
-                if interval > week:
-                    sessions.destroy(sessid)
-            # remove aged otks
-            otks = self.db.otks
-            for sessid in otks.list():
-                interval = now - otks.get(sessid, '__time')
-                if interval > week:
-                    otks.destroy(sessid)
-            sessions.set('last_clean', last_use=time.time())
+        if now - last_clean < hour:
+            return
+
+        self.db.sessions.clean(now)
+        self.db.otks.clean(now)
+        self.db.sessions.set('last_clean', last_use=time.time())
 
     def determine_user(self):
         ''' Determine who the user is
@@ -296,7 +290,7 @@ def determine_user(self):
             # get the user from the session
             try:
                 # update the lifetime datestamp
-                sessions.set(self.session, last_use=time.time())
+                sessions.updateTimestamp(self.session)
                 sessions.commit()
                 user = sessions.get(self.session, 'user')
             except KeyError:
@@ -575,6 +569,11 @@ def write(self, content):
             self.header()
         self.request.wfile.write(content)
 
+    def setHeader(self, header, value):
+        '''Override a header to be returned to the user's browser.
+        '''
+        self.additional_headers[header] = value
+
     def header(self, headers=None, response=None):
         '''Put up the appropriate header.
         '''