Wiki::Toolkit::Feed::Atom.3pm

Langue: en

Autres versions - même langue

Version: 2009-12-16 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME

   Wiki::Toolkit::Feed::Atom - A Wiki::Toolkit plugin to output RecentChanges Atom.

DESCRIPTION

This is an alternative access to the recent changes of a Wiki::Toolkit wiki. It outputs the Atom Syndication Format as described at <http://www.atomenabled.org/developers/syndication/>.

This module is a straight port of Wiki::Toolkit::Feed::RSS.

SYNOPSIS

   use Wiki::Toolkit;
   use Wiki::Toolkit::Feed::Atom;
 
   my $wiki = Wiki::Toolkit->new( ... );  # See perldoc Wiki::Toolkit
 
   # Set up the RSS feeder with the mandatory arguments - see
   # C<new()> below for more, optional, arguments.
   my $atom = Wiki::Toolkit::Feed::Atom->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',
     atom_link => 'http://example.com/?action=rc;format=atom',
   );
 
   print "Content-type: application/atom+xml\n\n";
   print $atom->recent_changes;

METHODS

new()

   my $atom = Wiki::Toolkit::Feed::Atom->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',,
     atom_link => 'http://example.com/?action=rc;format=atom',
 
     # Optional arguments:
     site_description     => 'My wiki about my stuff',
     software_name        => $your_software_name,     # e.g. "Wiki::Toolkit"
     software_version     => $your_software_version,  # e.g. "0.73"
     software_homepage    => $your_software_homepage, # e.g. "http://search.cpan.org/dist/CGI-Wiki/"
     encoding             => 'UTF-8'
   );

"wiki" must be a Wiki::Toolkit object. "make_node_url", if supplied, must be a coderef.

The mandatory arguments are:

•
wiki
•
site_name
•
site_url
•
make_node_url
•
html_equiv_link or recent_changes_link
•
atom_link

The three optional arguments

•
software_name
•
software_version
•
software_homepage

are used to generate the "generator" part of the feed.

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/atom+xml\n\n";
   print $atom->recent_changes;
 
   # Or get something other than the default of the latest 15 changes.
   print $atom->recent_changes( items => 50 );
   print $atom->recent_changes( days => 7 );
 
   # Or ignore minor edits.
   print $atom->recent_changes( ignore_minor_edits => 1 );
 
   # Personalise your feed further - consider only changes
   # made by Fred to pages about bookshops.
   print $atom->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 Atom 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 summary 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 'No description given for change'.
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 author for this item. Defaults to 'Anonymous'.

generate_node_list_feed

Generate and return an Atom feed for a list of nodes

generate_node_name_distance_feed

Generate a very cut down atom 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()

   print $atom->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.

parse_feed_timestamp

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

SEE ALSO

•
Wiki::Toolkit
•
<http://www.atomenabled.org/developers/syndication/>

MAINTAINER

The Wiki::Toolkit team, http://www.wiki-toolkit.org/. Copyright 2006-2009 Earle Martin and 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

Kake Pugh for originally writing Wiki::Toolkit::Feed::RSS and indeed Wiki::Toolkit itself.