view release on metacpan or  search on metacpan

Wyrd/Site/Pull.pm  view on Meta::CPAN

package Apache::Wyrd::Site::Pull;
use strict;
use base qw(Apache::Wyrd::Interfaces::IndexUser Apache::Wyrd::Interfaces::Setter Apache::Wyrd::Interfaces::Dater Apache::Wyrd);
use Apache::Wyrd::Services::SAK qw(token_parse);
our $VERSION = '0.98';

=pod

=head1 NAME

Apache::Wyrd::Site::Pull - Abstract class for Page Lists

=head1 SYNOPSIS

	#subclass Pull object to always ignore documents which have expired,
	#"expires" being an attribute of a Page object expressed in YYYYMMDD
	#form.
	package BASENAME::Pull;
	use base qw(Apache::Wyrd::Site::Pull);
	sub _date_fields {
		return ('published', 'expires');
	}

	sub _require_fields {
		return qw(expires);
	}

	sub _doc_filter {
		my $self = shift;
		my @docs = @_;
		my $today = $self->_today_yyyymmdd;
		@docs = grep {$_->{expires} > $today} @docs;
		return @docs;
	}

=head1 DESCRIPTION

Pull is an abstract ancestor class for NavPull and TagPull Wyrds which is
used to apply rules for all page entries in a site index which are to be
displayed on a page of that site.  See Apache::Wyrd::Site for details.

=head2 PERL METHODS

I<(format: (returns) name (arguments after self))>

=over

=item (array) C<_process_docs> (array)

Apply some transformation to every index entry.  Accepts an array (as
returned by C<Apache::Wyrd::Site::Index::search()>), and returns a copy of
the array with the transformation applied.

The default transformation is to change every date field of the array into a
human-readable form, as Apache::Wyrd::Interfaces::Dater::_date_string() and
to delete any false-value keys, so that all
C<Apache::Wyrd::Interfaces::Setter> methods will work consistently.
Generally, if you want to override this method in a subclass, you should
finish with a call to the SUPER class unless you have made allowances for
this need (i.e. C<$self->SUPER::_process_docs(@docs)>).

=cut

sub _process_docs {
	my ($self, @docs) = @_;
	my @out = ();
	foreach my $doc (@docs) {
		foreach my $key (keys(%$doc)) {
			$$doc{$key} = $self->_date_string(split(/[,-]/, $$doc{$key})) if (grep {$_ eq $key} $self->_date_fields);
			delete $$doc{$key} unless ($$doc{$key});#undefine missing bits for setter
		}
		push @out, $doc;
	}
	return @out;
}

=item (array) C<_date_fields> (void)

The array of fields that should be transformed from the standard YYYYMMDD
string into human-readable dates.  Default is the single field "published". 
Override this method to change this list.

=cut

sub _date_fields {
	return qw(published);
}

=item (array) C<_require_fields> (void)

The array of fields that must be in any entry requested from the site index.
 Generally, this is not necessary, since all fields are returned by default
except those in C<_skip_fields>.

=item (array) C<_skip_fields> (void)

The array of fields that have no use to Pulls, and should not be included in
the returned array of entries.  Defaults to "data", "timestamp", and
"digest", which are usually of interest only to the site index.  (see
C<Apache::Wyrd::Site::Index>).  Override this method to change this list.

=cut

sub _skip_fields {
	return qw(data timestamp digest);
}

=item (hashref) C<_search_params> (void)

This returns the value of the parameter to send to the site index objects in
order to apply the terms of C<_skip_fields> and C<_require_fields>.  It is
used by the TagPull and NavPull objects in their requests for an array of
documents matching their criteria.  Override only if you need to extend this
distinction beyond C<_skip_fields> and C<_require_fields>.

=cut

sub _search_params {
	my ($self) = @_;
	my %params = ();