gavinc/rss20

   1 # Blosxom Plugin: rss20
   2 # Author(s): Gavin Carr <gavin@openfusion.com.au>
   3 # Version: 0.002000
   4 # Requires: storydate
   5 # Suggests: absolute, storytags
   6 # Follows:  storydate
   7
   8 package rss20;
   9
  10 use strict;
  11
  12 use vars qw(
  13   $flavour
  14   $author_email
  15   $author_name
  16   $webmaster_email
  17   $permalink
  18   $trackback_link
  19   $copyright
  20   $generator
  21   $category_list
  22 );
  23
  24 # --- Configuration variables -----
  25
  26 # What flavour string to you want to use for your feed?
  27 $flavour = 'rss';
  28 #$flavour = 'rss20';
  29
  30 # What email address should be used as the default author email?
  31 # Recommended format is 'email (name)', but bare emails or mailto emails are ok too
  32 $author_email = 'author@example.com (A. U. Thor)';
  33
  34 # What name should be used as the default author name?
  35 # Define this only if you don't want to disclose an email address in $author_email.
  36 # It will be ignored if $author_email is set.
  37 $author_name = '';
  38
  39 # What email address should feed errors be reported to?
  40 # Recommended format is 'email (name)', but bare emails or mailto emails are ok too
  41 $webmaster_email = '';
  42 #$webmaster_email = 'webmaster@example.com (Web Master)';
  43
  44 # What do your story permalinks look like?
  45 # This must be single-quoted, to defer evaluation; blosxom namespace applies
  46 $permalink = '$url$path/$fn.$default_flavour';
  47
  48 # What link should be used for trackbacks on a story?
  49 # This must be single-quoted, to defer evaluation; blosxom namespace applies
  50 $trackback_link = '';
  51 # $trackback_link = '$url$path/$fn.writeback';
  52 # $trackback_link = '$url$path/$fn.$feedback::trackback_flavour';
  53
  54 # Copyright statement; leave blank to omit.
  55 $copyright = '';
  56
  57 # Generator that produced this feed
  58 $generator = "blosxom $blosxom::version";
  59
  60 # --------------------------------
  61 # __END_CONFIG__
  62
  63 $webmaster_email ||= $author_email;
  64
  65 my $channel_indent = 8;
  66 my $item_indent = 12;
  67
  68 # Escape <, >, and & to hex-encoded entities for max compatibility in text elements
  69 # See http://www.rssboard.org/rss-profile#data-types-characterdata
  70 my %escape_text = (
  71   '<' => '&#x3C;',
  72   '>' => '&#x3E;',
  73   '&' => '&#x26;',
  74 );
  75 my $escape_text_re = join '|' => keys %escape_text;
  76
  77 # Escape <, >, and & to standard html-encoded entities for in html elements
  78 my %escape_html = (
  79   '<' => '&lt;',
  80   '>' => '&gt;',
  81   '&' => '&amp;',
  82 );
  83 my $escape_html_re = join '|' => keys %escape_html;
  84
  85 sub start {
  86   _load_templates();
  87 }
  88
  89 my $do_encode = 0;
  90 sub story {
  91   my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
  92
  93   # Ignore flavours other than ours
  94   return unless $blosxom::flavour eq $flavour;
  95
  96   # Don't double-encode if someone else has already done it
  97   return unless $do_encode || $blosxom::encode_xml_entities;
  98
  99   # Because we're inside a loop, we set $do_encode for runs after the first
 100   unless ($do_encode) {
 101     $do_encode = 1;
 102     $blosxom::encode_xml_entities = 0;
 103   }
 104
 105   # Encode and reset encode_xml_entities flag
 106   $$title_ref = _escape_text( $$title_ref );
 107   $$body_ref  = _escape_html( $$body_ref );
 108
 109   $category_list = '';
 110   if ($blosxom::plugins{storytags}) {
 111     for (@storytags::taglist) {
 112       $category_list .= qq(<category>$_</category>\n) . ' ' x $item_indent;
 113     }
 114   }
 115 }
 116
 117 # --- Private subroutines
 118
 119 sub _escape_text {
 120   my ($text) = @_;
 121   $text =~ s/($escape_text_re)/$escape_text{$1}/g;
 122   return $text;
 123 }
 124
 125 sub _escape_html {
 126   my ($html) = @_;
 127   $html =~ s/($escape_html_re)/$escape_html{$1}/g;
 128   return $html;
 129 }
 130
 131 sub _load_templates {
 132   $blosxom::template{$flavour}{'content_type'} = 'text/xml; charset=$blog_encoding';
 133
 134   $blosxom::template{$flavour}{'date'} = "\n";
 135
 136   $blosxom::template{$flavour}{'head'} = <<HEAD;
 137 <?xml version="1.0" encoding="$blosxom::blog_encoding"?>
 138 <rss version="2.0"
 139     xmlns:dc="http://purl.org/dc/elements/1.1/"
 140     xmlns:sy="http://purl.org/rss/1.0/modules/syndication/"
 141     xmlns:atom="http://www.w3.org/2005/Atom">
 142
 143     <channel>
 144         <title>$blosxom::blog_title</title>
 145         <link>$blosxom::url/</link>
 146 HEAD
 147
 148   if ($blosxom::path_info) {
 149     $blosxom::template{$flavour}{'head'} .=
 150      ' ' x $channel_indent .
 151      qq(<category>$blosxom::path_info</category>\n);
 152   }
 153   if ($blosxom::blog_description) {
 154     $blosxom::template{$flavour}{'head'} .=
 155      ' ' x $channel_indent .
 156       qq(<description>$blosxom::blog_description</description>\n);
 157   }
 158   if ($rss20::author_email) {
 159     $blosxom::template{$flavour}{'head'} .=
 160      ' ' x $channel_indent .
 161       qq(<managingEditor>$rss20::author_email</managingEditor>\n);
 162   }
 163   elsif ($rss20::author_name) {
 164     $blosxom::template{$flavour}{'head'} .=
 165      ' ' x $channel_indent .
 166       qq(<dc:creator>$rss20::author_name</dc:creator>\n);
 167   }
 168   if ($rss20::webmaster_email) {
 169     $blosxom::template{$flavour}{'head'} .=
 170      ' ' x $channel_indent .
 171       qq(<webMaster>$rss20::webmaster_email</webMaster>\n);
 172   }
 173   if ($rss20::copyright) {
 174     $blosxom::template{$flavour}{'head'} .=
 175      ' ' x $channel_indent .
 176       qq(<copyright>$rss20::copyright</copyright>\n);
 177   }
 178   my $path_info = $blosxom::path_info_orig || "/$blosxom::path_info";
 179   $blosxom::template{$flavour}{'head'} .= <<HEAD;
 180         <pubDate>\$storydate::latest_rfc822</pubDate>
 181         <language>$blosxom::blog_language</language>
 182         <generator>$rss20::generator</generator>
 183         <atom:link href="$blosxom::url$path_info" rel="self" type="application/rss+xml" />
 184         <sy:updatePeriod>hourly</sy:updatePeriod>
 185         <sy:updateFrequency>1</sy:updateFrequency>
 186         <sy:updateBase>2000-01-01T12:00+00:00</sy:updateBase>
 187 HEAD
 188
 189   $blosxom::template{$flavour}{'story'} = <<STORY;
 190
 191         <item>
 192             <title>\$title</title>
 193             <link>$rss20::permalink</link>
 194             <guid isPermaLink="true">$rss20::permalink</guid>
 195             <pubDate>\$storydate::story_rfc822</pubDate>
 196 STORY
 197
 198   if ($rss20::trackback_link) {
 199     $blosxom::template{$flavour}{'story'} .=
 200       ' ' x $item_indent .
 201       qq(<comments>$rss20::trackback_link</comments>\n);
 202   }
 203   $blosxom::template{$flavour}{'story'} .= <<STORY;
 204             \$rss20::category_list<description>\$body
 205             </description>
 206         </item>
 207 STORY
 208
 209   $blosxom::template{$flavour}{'foot'} = <<'FOOT';
 210
 211     </channel>
 212 </rss>
 213 FOOT
 214
 215   1;
 216 }
 217
 218
 219 1;
 220
 221 __END__
 222
 223 =head1 NAME
 224
 225 rss20 - blosxom plugin to generate an RSS 2.0 feed of your blog
 226
 227 =head1 DESCRIPTION
 228
 229 rss20 is a blosxom plugin to generate an RSS 2.0 feed of your blog. It
 230 is self-contained, including the required flavours, and has a bunch of
 231 configuration variables to allow for configuration.
 232
 233 =head2 CONFIGURATION
 234
 235 The following package variables can be configured:
 236
 237 =over 4
 238
 239 =item $flavour
 240
 241 Flavour string to use for your feed (typically 'rss' or 'rss20').
 242
 243 =item $author_email
 244
 245 Default author email address for posts.
 246
 247 =item $webmaster_email
 248
 249 Email address to use for webmaster responsible for the feed (defaults
 250 to $author_email).
 251
 252 =item $permalink
 253
 254 Story permalink. Default is '$url$path/$fn.$default_flavour'.
 255 Note that this value should probably be single quoted to defer
 256 variable evaluation until rendering time.
 257
 258 =item $trackback_link
 259
 260 Story trackback or comment link. Default is ''. Useful if you
 261 are using a comments plugin like C<writeback> or C<feedback>,
 262 and the format you want will be plugin-dependant.
 263
 264 Like $permalink, this value should be single quoted to defer
 265 variable evaluation till rendering time.
 266
 267 =item $copyright
 268
 269 Default copyright clause for posts, if any.
 270
 271 =back
 272
 273 =head1 USAGE
 274
 275 rss20 should be loaded relatively late, since you'll typically want
 276 plugins that manipulate your story content to have run already. It
 277 also should be run after the 'story' or 'prefs' plugins if you want
 278 to use those to customise your configuration variables.
 279
 280
 281 =head1 SEE ALSO
 282
 283 Blosxom: http://blosxom.sourceforge.net/
 284
 285 rss20 is based on the 'atomfeed' and 'rss10' plugins, by Rael
 286 Dornfest and contributors.
 287
 288
 289 =head1 BUGS
 290
 291 Please report bugs either directly to the author or to the blosxom
 292 development mailing list: <blosxom-devel@lists.sourceforge.net>.
 293
 294
 295 =head1 AUTHOR
 296
 297 Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
 298
 299
 300 =head1 LICENSE
 301
 302 Copyright 2007 Gavin Carr.
 303
 304 This plugin is licensed under the same terms as blosxom itself i.e.
 305
 306 Permission is hereby granted, free of charge, to any person obtaining a
 307 copy of this software and associated documentation files (the "Software"),
 308 to deal in the Software without restriction, including without limitation
 309 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 310 and/or sell copies of the Software, and to permit persons to whom the
 311 Software is furnished to do so, subject to the following conditions:
 312
 313 The above copyright notice and this permission notice shall be included
 314 in all copies or substantial portions of the Software.
 315
 316 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 317 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 318 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 319 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 320 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 321 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 322 OTHER DEALINGS IN THE SOFTWARE.
 323
 324 =cut
 325
 326 # vim:ft=perl