OpenGuides::Feed - generate data feeds for OpenGuides in various formats.

NAME

DESCRIPTION

SYNOPSIS

    use Wiki::Toolkit;
    use OpenGuides::Config;
    use OpenGuides::Feed;

    my $wiki = Wiki::Toolkit->new( ... );
    my $config = OpenGuides::Config->new( file => "wiki.conf" );
    my $feed = OpenGuides::Feed->new( wiki       => $wiki,
                                      config     => $config,
                                      og_version => '1.0', ); 

    # Ten most recent changes in RSS format.
    my %args = ( items     => 10,
                 feed_type => 'rss', 
                 also_return_timestamp => 1 );
    my ($feed_output,$feed_timestamp) = $feed->make_feed( %args );

    print "Content-Type: application/rdf+xml\n";
    print "Last-Modified: " . $feed_timestamp . "\n\n";
    print $feed_output;

METHODS

SEE ALSO

AUTHOR

COPYRIGHT

CREDITS

package OpenGuides::Feed;

use strict;

use vars qw( $VERSION );
$VERSION = '0.02';

use Wiki::Toolkit::Feed::Atom;
use Wiki::Toolkit::Feed::RSS;
use Time::Piece;
use URI::Escape;
use Carp 'croak';

use base qw( Class::Accessor );
# Add more here if we need them - this one added for testing purposes.
my @variables = qw( html_equiv_link );
OpenGuides::Feed->mk_accessors( @variables );

sub new {
    my ($class, @args) = @_;
    my $self = {};
    bless $self, $class;
    $self->_init(@args);
}

sub _init {
    my ($self, %args) = @_;

    my $wiki = $args{wiki};
    
    unless ( $wiki && UNIVERSAL::isa( $wiki, "Wiki::Toolkit" ) ) {
       croak "No Wiki::Toolkit object supplied.";
    }
    $self->{wiki} = $wiki;

    my $config = $args{config};

    unless ( $config && UNIVERSAL::isa( $config, "OpenGuides::Config" ) ) {
        croak "No OpenGuides::Config object supplied.";
    }
    $self->{config} = $config;

    $self->{make_node_url} = sub {
        my ($node_name, $version) = @_;

        my $config = $self->{config};
    
        my $node_url = $config->script_url . uri_escape($config->script_name) . '?';
        $node_url .= 'id=' if defined $version;
        $node_url .= uri_escape($self->{wiki}->formatter->node_name_to_node_param($node_name));
        $node_url .= ';version=' . uri_escape($version) if defined $version;

        $node_url;
      };  
    $self->{site_name}        = $config->site_name . " - Recent Changes";
    $self->{default_city}     = $config->default_city      || "";
    $self->{default_country}  = $config->default_country   || "";
    $self->{site_description} = $config->site_desc         || "";
    $self->{og_version}       = $args{og_version};
    $self->{html_equiv_link}  = $self->{config}->script_url
                                . $self->{config}->script_name . '?action=rc';

    $self;
}

sub set_feed_name_and_url_params {
    my ($self, $name, $url) = @_;

    unless($url =~ /^http/) {
        my $b_url = $self->{config}->script_url;
        unless($url =~ /\.cgi\?/) { $b_url .= "?"; }
        $b_url .= $url;
        $url = $b_url;
    }

    $self->{site_name} = $self->{config}->{site_name} . " - " . $name;
    $self->{html_equiv_link} = $url;
}

sub make_feed {
    my ($self, %args) = @_;
    
    my $feed_type = $args{feed_type};
    my $feed_listing = $args{feed_listing};
    
    my %known_listings = (
                          'recent_changes' => 1,
                          'node_all_versions' => 1,
                         );
                      
    croak "No feed listing specified" unless $feed_listing;
    croak "Unknown feed listing: $feed_listing" unless $known_listings{$feed_listing};


    # Tweak any settings, as required by our feed listing
    if ($feed_listing eq 'node_all_versions') {
        $self->set_feed_name_and_url_params(
                    "All versions of ".$args{'name'},
                    "action=list_all_versions;id=".$args{'name'}
        );
    }


    # Fetch the right Wiki::Toolkit::Feeds::Listing instance to use
    my $maker = $self->fetch_maker($feed_type);


    # Call the appropriate feed listing from it
    if ($feed_listing eq 'recent_changes') {
        return $maker->recent_changes(%args);
    }
    elsif ($feed_listing eq 'node_all_versions') {
        return $maker->node_all_versions(%args);
    }
}

sub build_feed_for_nodes {
    my ($self, $format, @nodes) = @_;
    return $self->render_feed_for_nodes($format, undef, 1, @nodes);
}

sub build_mini_feed_for_nodes {
    my ($self, $format, @nodes) = @_;
    return $self->render_feed_for_nodes($format, undef, 0, @nodes);
}

sub render_feed_for_nodes {
    my ($self, $format, $html_url, $is_full, @nodes) = @_;

    # Grab our feed maker
    my $maker = $self->fetch_maker($format);

    # Find our newest node, so we can use that for the feed timestamp
    my $newest_node;
    foreach my $node (@nodes) {
        if($node->{last_modified}) {
            if((!$newest_node) || ($node->{last_modified} gt $newest_node->{last_modified})) {
                $newest_node = $node;
            }
        }
    }

    # Grab the timestamp, and do our header
    my $timestamp = $maker->feed_timestamp($newest_node);

    my $feed = "Last-Modified: ".$timestamp."\n\n";

    # Generate the feed itself
    if($is_full) {
        $feed .= $maker->generate_node_list_feed($timestamp, @nodes);
    } else {
        $feed .= $maker->generate_node_name_distance_feed($timestamp, @nodes);
    }

    return $feed;
}

sub default_content_type {
    my ($self,$feed_type) = @_;

    my $content_type;

    if ($feed_type eq 'rss') {
        $content_type = "application/rdf+xml";
    }
    elsif ($feed_type eq 'atom') {
        $content_type = "application/atom+xml";
    }
    else {
        croak "Unknown feed type given: $feed_type";
    }

    return $content_type;
}

sub fetch_maker {
    my ($self,$feed_type) = @_;

    my %known_types = (
                          'atom'  => \&atom_maker,
                          'rss' => \&rss_maker,
                      );

    croak "No feed type specified" unless $feed_type;
    croak "Unknown feed type: $feed_type" unless $known_types{$feed_type};

    return &{$known_types{$feed_type}};
}

sub atom_maker {
    my $self = shift;
  
    unless ($self->{atom_maker}) {
        $self->{atom_maker} = Wiki::Toolkit::Feed::Atom->new(
            wiki                => $self->{wiki},
            site_name           => $self->{site_name},
            site_url            => $self->{config}->script_url,
            site_description    => $self->{site_description},
            make_node_url       => $self->{make_node_url},
            html_equiv_link     => $self->{html_equiv_link},
            atom_link           => $self->{html_equiv_link} . ";format=atom",
            software_name       => 'OpenGuides',
            software_homepage   => 'http://openguides.org/',
            software_version    => $self->{og_version},
            encoding            => $self->{config}->http_charset,
        );
    }
    
    $self->{atom_maker};
}

sub rss_maker {
    my $self = shift;

    unless ($self->{rss_maker}) {
        $self->{rss_maker} = Wiki::Toolkit::Feed::RSS->new(
            wiki                => $self->{wiki},
            site_name           => $self->{site_name},
            site_url            => $self->{config}->script_url,
            site_description    => $self->{site_description},
            make_node_url       => $self->{make_node_url},
            html_equiv_link     => $self->{html_equiv_link},
            software_name       => 'OpenGuides',
            software_homepage   => 'http://openguides.org/',
            software_version    => $self->{og_version},
            encoding            => $self->{config}->http_charset,
        );
    }
    
    $self->{rss_maker};
}

sub feed_timestamp {
    my ($self, %args) = @_;

    # Call the compatability timestamping method on the RSS Feed.
    # People should really just pass in also_return_timestamp to the
    #  feed method, and get the timestamp at the same time as their data
    $self->rss_maker->rss_timestamp(%args);
}

1;