added ability to implement new templating utility methods

Author: Richard Jones

CHANGES.txt

@@ -20,6 +20,10 @@ are given with the most recent entry first.
 - fixed history to display username instead of userid
 - shipped templates didn't import all hyperdb types in dbinit.py
 - fixed bug in Interval serialisation
+- handle "unset" status in status auditor (sf bug 621250)
+- issues in 'done-cbb' are now also moved to 'chatting' on new messages
+- implemented the missing Interval.__add__
+- added ability to implement new templating utility methods
 
 
 2002-10-02 0.5.0

doc/customizing.txt

@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.56 $
+:Version: $Revision: 1.57 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -1334,14 +1334,21 @@ or the python expression::
 The utils variable
 ~~~~~~~~~~~~~~~~~~
 
-Note: this is implemented by the roundup.cgi.templating.TemplatingUtils class.
+Note: this is implemented by the roundup.cgi.templating.TemplatingUtils class,
+but it may be extended as described below.
 
 =============== =============================================================
 Method          Description
 =============== =============================================================
 Batch           return a batch object using the supplied list
 =============== =============================================================
 
+You may add additional utility methods by writing them in your tracker
+``interfaces.py`` module's ``TemplatingUtils`` class. See `adding a time log
+to your issues`_ for an example. The TemplatingUtils class itself will have a
+single attribute, ``client``, which may be used to access the ``client.db``
+when you need to perform arbitrary database queries.
+
 Batching
 ::::::::
 
@@ -2520,10 +2527,35 @@ able to give a summary of the total time spent on a particular issue.
    isn't it handy? The important change is setting the action to
    "edit_with_timelog" for edit operations (where the item exists)
 
-6. Display the time log for an issue::
+6. We want to display a total of the time log times that have been accumulated
+   for an issue. To do this, we'll need to actually write some Python code,
+   since it's beyond the scope of PageTemplates to perform such calculations.
+   We do this by adding a method to the TemplatingUtils class in our tracker
+   ``interfaces.py`` module::
+
+
+    class TemplatingUtils:
+        ''' Methods implemented on this class will be available to HTML
+            templates through the 'utils' variable.
+        '''
+        def totalTimeSpent(self, times):
+            ''' Call me with a list of timelog items (which have an Interval 
+                "period" property)
+            '''
+            total = Interval('')
+            for time in times:
+                total += time.period._value
+            return total
+
+   As indicated in the docstrings, we will be able to access the
+   ``totalTimeSpent`` method via the ``utils`` variable in our templates. See
+
+7. Display the time log for an issue::
 
      <table class="otherinfo" tal:condition="context/times">
-      <tr><th colspan="3" class="header">Time Log</th></tr>
+      <tr><th colspan="3" class="header">Time Log
+       <tal:block tal:replace="python:utils.totalTimeSpent(context.times)" />
+      </th></tr>
       <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
       <tr tal:repeat="time context/times">
        <td tal:content="time/creation"></td>
@@ -2532,9 +2564,12 @@ able to give a summary of the total time spent on a particular issue.
       </tr>
      </table>
 
-   I put this just above the Messages log in my issue display.
+   I put this just above the Messages log in my issue display. Note our use
+   of the ``totalTimeSpent`` method which will total up the times for the
+   issue and return a new Interval. That will be automatically displayed in
+   the template as text like "+ 1y 2:40" (1 year, 2 hours and 40 minutes).
 
-6. If you're using a persistent web server - roundup-server or mod_python for
+8. If you're using a persistent web server - roundup-server or mod_python for
    example - then you'll need to restart that to pick up the code changes.
    When that's done, you'll be able to use the new time logging interface.
 

roundup/cgi/templating.py

@@ -130,16 +130,27 @@ class RoundupPageTemplate(PageTemplate.PageTemplate):
           The current tracker config.
         *db*
           The current database, used to access arbitrary database items.
+        *utils*
+          This is a special class that has its base in the TemplatingUtils
+          class in this file. If the tracker interfaces module defines a
+          TemplatingUtils class then it is mixed in, overriding the methods
+          in the base class.
     '''
     def getContext(self, client, classname, request):
+        # construct the TemplatingUtils class
+        utils = TemplatingUtils
+        if hasattr(client.instance.interfaces, 'TemplatingUtils'):
+            class utils(client.instance.interfaces.TemplatingUtils, utils):
+                pass
+
         c = {
              'options': {},
              'nothing': None,
              'request': request,
              'db': HTMLDatabase(client),
              'config': client.instance.config,
              'tracker': client.instance,
-             'utils': TemplatingUtils(client),
+             'utils': utils(client),
              'templates': Templates(client.instance.config.TEMPLATES),
         }
         # add in the item if there is one

roundup/templates/classic/interfaces.py

@@ -15,7 +15,7 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: interfaces.py,v 1.15 2002-09-09 23:55:19 richard Exp $
+# $Id: interfaces.py,v 1.16 2002-10-11 01:26:43 richard Exp $
 
 from roundup import mailgw 
 from roundup.cgi import client
@@ -26,6 +26,12 @@ class Client(client.Client):
     ''' 
     pass
 
+class TemplatingUtils:
+    ''' Methods implemented on this class will be available to HTML templates
+        through the 'utils' variable.
+    '''
+    pass
+
 class MailGW(mailgw.MailGW): 
     ''' derives basic mail gateway implementation from the standard module, 
         with any specific extensions 

roundup/templates/minimal/interfaces.py

@@ -15,7 +15,7 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: interfaces.py,v 1.1 2002-09-26 04:15:07 richard Exp $
+# $Id: interfaces.py,v 1.2 2002-10-11 01:26:43 richard Exp $
 
 from roundup import mailgw 
 from roundup.cgi import client
@@ -26,6 +26,12 @@ class Client(client.Client):
     ''' 
     pass
 
+class TemplatingUtils:
+    ''' Methods implemented on this class will be available to HTML templates
+        through the 'utils' variable.
+    '''
+    pass
+
 class MailGW(mailgw.MailGW): 
     ''' derives basic mail gateway implementation from the standard module, 
         with any specific extensions