Roundup Tracker

The roundup templating system, ZPT, allows for generation of feeds from queries in just the same way HTML is generated. This is completely dynamic and can produce feeds based on search criteria, which is very useful for getting precise information from roundup.

Dynamically generating your feeds (as opposed to DetectorBasedFeedGeneration) presents some advantages:

  1. You can be as flexible as the HTML pages, so you can generate ad hoc feeds based on searches or pretty much any other criteria you or your users can think of.
  2. You can play around with the templates on a live system without affecting anyone, with the detector you can break an issue tracker's editing ability if you break the detector.
  3. You can restrict what any given user can see, so a public tracker with private issues in it as well can present different lists of changes to different users from the same feed template.

There are also drawbacks:

  1. The biggest drawback on a public site is load, every time the feed is requested the page has to be generated. So this can place a heavy load on the server if people have news readers with a very high refresh frequency (down to 5 minutes in some cases).
  2. It's harder to present information on what has changed without writing a bit of logic to put together a list of changes. This means that users might not immediately be able to see what has changed in a given issue.

To add an atom 0.3 feed to an issue tracker you can do the following:

  1. Create a file called issue.index.xml in your tracker instance's html folder and add the following to it:

    <?xml version="1.0" encoding="utf-8"?>
  <feed version="0.3" xmlns="http://purl.org/atom/ns#"
        xmlns:tal="http://xml.zope.org/namespaces/tal"
        xmlns:metal="http://xml.zope.org/namespaces/metal">
    <title>Issues - <tal:block tal:replace="config/TRACKER_NAME" /></title>
    <link rel="alternate" type="text/html" tal:content="config/TRACKER_WEB">link</link>
    <tal:block tal:omit-tag="" tal:repeat="i request/batch">
      <entry>
          <title tal:content="i/title">title</title>
          <link rel="alternate" type="text/html" tal:content="string:${config/TRACKER_WEB}issue${i/id}">link</link>
          <id tal:content="python:config.TRACKER_NAME.replace(' ', '_') + ':issue' + i.id">id</id>
          <summary mode="escaped" type="text/html" tal:content="i/history"></summary>
          <issued tal:content="i/creation">issued</issued>
          <modified tal:content="i/activity">modified</modified>
     </entry>
   </tal:block>
 </feed>
  2. Any time you want to see an atom version of either a search result of an issue listing add '&@template=index.xml' to the URL, e.g. 'http://example.com/issues/issue?@template=index.xml'.

There are a couple of gotchas you have to watch out for:

  1. You must put in the XML namespaces ('xmlns:tal="http://xml.zope.org/namespaces/tal"' and 'xmlns:metal="http://xml.zope.org/namespaces/metal"') into the XML template or else ZPT can't see the tal and metal expressions. You know it hasn't picked up on the namespaces properly when you just see your template with the tal expressions left intact when you request a page.

  2. Currently only '.xml' is recognised as XML, anything else gets passed throught the HTML processor instead of the XML processor. This might not be immediately obvious but this does lead to a couple of issues:

    1. The wrong mime type is used in the request (this can confuse some news readers, and is plain incorrect).
    2. Certain tags can't contain content in HTML pages, so in the atom example above you would get an error about the '<link>' tag.

    If you want to make roundup recognise more document types you need to register them in the python mimetypes module in roundup's 'cgi/templating.py':

    ...
import sys, cgi, urllib, os, re, os.path, time, errno, mimetypes

# Register some new types
mimetypes.add_type("text/xml", ".rss")

from roundup import hyperdb, date, rcsv
from roundup.i18n import _
...

    This requires hacking roundup's code so is only useful in situations where you really, really want a particular extension. It might make more sense for things like PDF generation, or generating XML with a particular mime type (e.g. 'application/xhtml+xml' for XHTML documents).