rss/README

   1 About:
   2 rss.pl is meant to provide an extensible tool for creating RSS 0.91
   3 formatted files suitable for syndication.  The script relies on two
   4 external files for configuration information.  Rather than trying to
   5 explain how this occurs, I'll show you using the provided lastAcquired
   6 files.  There are currently three rss feeds bundled in this tarball
   7 (lastAcquired, longestUnseen, and mostReserved), the config files for
   8 each of these should be modified to suit your local site.  A smallish
   9 Koha image (sm-koha-icon.jpg) is included as well.
  10
  11 Dependencies:
  12 rss.pl depends on an installed Koha system, and uses the C4::Context
  13 module it provides.
  14
  15 Details:
  16 rss.pl is meant to be run from cron (probably once a day or so -- more
  17 often at larger libraries depending on the report being generated).  It
  18 is invoked like this (in the case of lastAcquired):
  19
  20  rss.pl /path/to/rssKoha/lastAcquired.conf
  21
  22 The basic process is that rss reads the config file
  23 (lastAcquired.conf) to determine RSS header information, the SQL query
  24 used to generate the results, and the HTML::Template style used to
  25 format the output.  Since you'll likely to want to create your own RSS
  26 content, or at least modify the ones present here, let's review the
  27 config file and the template file.
  28
  29 A config file is divided into three sections; channel, image, and
  30 config.  A section begins with the name of the section occuring alone
  31 on a line, and ends with the beginning of the next section (or the end
  32 of the file).  Each of these sections contains series of configuration
  33 options in the form:
  34
  35 name=content
  36
  37 The content section can contain spaces, but not newlines, special
  38 characters, or html mark-up.  It's also important that there are no
  39 blank lines within the config file.
  40
  41 Here's the lastAquired.conf by way of example:
  42
  43 channel
  44 title=Recent Koha Acquisitions
  45 link=http://www.koha.org
  46 desc=The 15 most recent acquisitions
  47 lang=en
  48 lastBuild=Fri, 09 May 2003 08:00:00
  49 image
  50 title=Koha, the worlds best Open Source Library System
  51 url=http://www.koha.org/images/foo.jpg
  52 link=http://www.koha.org
  53 config
  54 tmpl=lastAcquired.tmpl
  55 output=lastAcquired.xml
  56 query=select biblioitems.isbn as isbn, biblio.title as title, biblio.author as author from biblio, biblioitems, items where biblioitems.biblionumber = items.biblionumber and biblio.biblionumber = items.biblionumber and items.dateaccessioned is not NULL order by items.dateaccessioned desc
  57
  58
  59 This data (and the data acquired from the query) are then used to fill
  60 in the template.  Most of the template is boilerplate and should not
  61 be edited.  The section within the <TMPL_LOOP NAME=ITEMS>
  62 ... </TMPL_LOOP> is the part which can be modified to create your own
  63 RSS content.
  64
  65 Here's the lastAcquired.tmpl file:
  66
  67 <?xml version="1.0" encoding="UTF-8"?>
  68
  69 <!DOCTYPE rss PUBLIC "-//Netscape Communications/DTD RSS 0.91/EN"
  70           "http://my.netscape.com/publish/formats/rss-0.91.dtd">
  71
  72 <rss version="0.91">
  73
  74 <channel>
  75  <title><TMPL_VAR CHANNELTITLE></title>
  76  <link><TMPL_VAR CHANNELLINK></link>
  77  <description><TMPL_VAR CHANNELDESC></description>
  78  <language><TMPL_VAR CHANNELLANG></language>
  79  <lastBuildDate><TMPL_VAR CHANNELLASTBUILD></lastBuildDate>
  80
  81  <image>
  82   <title><TMPL_VAR IMAGETITLE></title>
  83   <url><TMPL_VAR IMAGEURL></url>
  84   <link><TMPL_VAR IMAGELINK></link>
  85  </image>
  86
  87 <TMPL_LOOP NAME=ITEMS>
  88  <item>
  89   <title><TMPL_VAR TITLE>, by <TMPL_VAR AUTHOR></title>
  90   <link>http://opac.library.org.nz/cgi-bin/koha/opac-searchresults.pl?isbn=<TMPL_VAR ISBN></link>
  91
  92  </item>
  93 </TMPL_LOOP>
  94
  95 </channel>
  96 </rss>
  97
  98 Credits:
  99 Originally written by Pat Eyler (pate@eylerfamily.org), suggestions,
 100 advice, and help came from 'Content Syndication with RSS', Chris
 101 Cormack, Mike Hansen, Steve Tonnesen and a variety of folks on #koha at
 102 irc.katipo.co.nz.