/ 
Wiki-Toolkit-0.84
River stage one • 6 direct dependents • 6 total dependents
/ Wiki::Toolkit::Feed::RSS

NAME

Wiki::Toolkit::Feed::RSS - Output RecentChanges RSS for Wiki::Toolkit.

DESCRIPTION

This is an alternative access to the recent changes of a Wiki::Toolkit wiki. It outputs RSS as described by the ModWiki proposal at http://www.usemod.com/cgi-bin/mb.pl?ModWiki

SYNOPSIS

use Wiki::Toolkit;
use Wiki::Toolkit::Feed::RSS;

my $wiki = CGI::Wiki->new( ... );  # See perldoc Wiki::Toolkit

# Set up the RSS feeder with the mandatory arguments - see
# C<new()> below for more, optional, arguments.
my $rss = Wiki::Toolkit::Feed::RSS->new(
  wiki                => $wiki,
  site_name           => 'My Wiki',
  site_url            => 'http://example.com/',
  make_node_url       => sub
                         {
                           my ($node_name, $version) = @_;
                           return 'http://example.com/?id=' . uri_escape($node_name) . ';version=' . uri_escape($version);
                         },
  html_equiv_link     => 'http://example.com/?RecentChanges',
  encoding            => 'UTF-8'
);

print "Content-type: application/xml\n\n";
print $rss->recent_changes;

METHODS

new()

my $rss = Wiki::Toolkit::Feed::RSS->new(
  # Mandatory arguments:
  wiki                 => $wiki,
  site_name            => 'My Wiki',
  site_url             => 'http://example.com/',
  make_node_url        => sub
                          {
                            my ($node_name, $version) = @_;
                            return 'http://example.com/?id=' . uri_escape($node_name) . ';version=' . uri_escape($version);
                          },
  html_equiv_link  => 'http://example.com/?RecentChanges',

  # Optional arguments:
  site_description     => 'My wiki about my stuff',
  interwiki_identifier => 'MyWiki',
  make_diff_url        => sub
                          {
                            my $node_name = shift;
                            return 'http://example.com/?diff=' . uri_escape($node_name)
                          },
  make_history_url     => sub
                          {
                            my $node_name = shift;
                            return 'http://example.com/?hist=' . uri_escape($node_name)
                          },
  software_name        => $your_software_name,     # e.g. "CGI::Wiki"
  software_version     => $your_software_version,  # e.g. "0.73"
  software_homepage    => $your_software_homepage, # e.g. "http://search.cpan.org/dist/Wiki-Toolkit/"
);

wiki must be a Wiki::Toolkit object. make_node_url, and make_diff_url and make_history_url, if supplied, must be coderefs.

The mandatory arguments are:

  • wiki

  • site_name

  • site_url

  • make_node_url

  • html_equiv_link or recent_changes_link

The three optional arguments

  • software_name

  • software_version

  • software_homepage

are used to generate DOAP (Description Of A Project - see http://usefulinc.com/doap) metadata for the feed to show what generated it.

The optional argument

  • encoding

will be used to specify the character encoding in the feed. If not set, will default to the wiki store's encoding.

recent_changes()

$wiki->write_node(
                   'About This Wiki',
                   'blah blah blah',
                       $checksum,
                       {
                         comment  => 'Stub page, please update!',
                         username => 'Fred',
                       }
);

print "Content-type: application/xml\n\n";
print $rss->recent_changes;

# Or get something other than the default of the latest 15 changes.
print $rss->recent_changes( items => 50 );
print $rss->recent_changes( days => 7 );

# Or ignore minor edits.
print $rss->recent_changes( ignore_minor_edits => 1 );

# Personalise your feed further - consider only changes
# made by Fred to pages about bookshops.
print $rss->recent_changes(
           filter_on_metadata => {
                       username => 'Fred',
                       category => 'Bookshops',
                     },
            );

If using filter_on_metadata, note that only changes satisfying all criteria will be returned.

Note: Many of the fields emitted by the RSS generator are taken from the node metadata. The form of this metadata is not mandated by Wiki::Toolkit. Your wiki application should make sure to store some or all of the following metadata when calling write_node:

comment - a brief comment summarising the edit that has just been made; will be used in the RDF description for this item. Defaults to the empty string.
username - an identifier for the person who made the edit; will be used as the Dublin Core contributor for this item, and also in the RDF description. Defaults to the empty string.
host - the hostname or IP address of the computer used to make the edit; if no username is supplied then this will be used as the Dublin Core contributor for this item. Defaults to the empty string.
major_change - true if the edit was a major edit and false if it was a minor edit; used for the importance of the item. Defaults to true (ie if major_change was not defined or was explicitly stored as undef).

feed_timestamp()

print $rss->feed_timestamp();

Returns the timestamp of the feed in POSIX::strftime style ("Tue, 29 Feb 2000 12:34:56 GMT"), which is equivalent to the timestamp of the most recent item in the feed. Takes the same arguments as recent_changes(). You will most likely need this to print a Last-Modified HTTP header so user-agents can determine whether they need to reload the feed or not.

generate_node_list_feed

Generate and return an RSS feed for a list of nodes

generate_node_name_distance_feed

Generate a very cut down rss feed, based just on the nodes, their locations (if given), and their distance from a reference location (if given).

Typically used on search feeds.

feed_timestamp

Generate the timestamp for the RSS, based on the newest node (if available). Will return a timestamp for now if no node dates are available

parse_feed_timestamp

Take a feed_timestamp and return a Time::Piece object.

SEE ALSO

MAINTAINER

The Wiki::Toolkit project. Originally by Kake Pugh <kake@earth.li>.

COPYRIGHT AND LICENSE

Copyright 2003-4 Kake Pugh. Copyright 2005 Earle Martin. Copyright 2006-2009 the Wiki::Toolkit team

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

THANKS

The members of the Semantic Web Interest Group channel on irc.freenode.net, #swig, were very useful in the development of this module.