Internal method, to build all the stuff that will go at the start of a feed. Outputs the feed header, and initial feed info.

Internal method, to build all the stuff that will go at the end of a feed.

<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

Generate the timestamp for the Atom, 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.

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'.

`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.