NAME

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

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;
        }

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.

PERL METHODS

(format: (returns) name (arguments after self))

(array) _process_docs (array)

Apply some transformation to every index entry. Accepts an array (as returned by 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 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. $self-SUPER::_process_docs(@docs)>).

(array) _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.

(array) _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 _skip_fields.

(array) _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 Apache::Wyrd::Site::Index). Override this method to change this list.

(hashref) _search_params (void)

This returns the value of the parameter to send to the site index objects in order to apply the terms of _skip_fields and _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 _skip_fields and _require_fields.

(array) _process_eventdate (array)

If the index entry includes the field "eventdate", this method can be called in order to filter out items which do not fall within an event window. Note that "eventdate" is not one of the default attributes of Apache::Wyrd::Site::Page, and you will need to add it to the attributes list (see _attribs in the documentation for the Page Wyrd) as well as overriding the _process_docs method in order to include this method in the transformation.

Where the pull's attribute is set to a date range in the standard eight-day form (see Apache::Wyrd::Interfaces::Dater) with a comma (i.e. eventdate="YYYYMMDD,YYYYMMDD"), the eventdate attribute of the page entry will be compared to this window, and if there is no overlap, the document will not appear in the Tag/NavPull.

Also acceptable as a value for eventdate is a positive or negative integer, indicating so many days in the future or the past.

If unset, the Pull's contents will be unaffected.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

Apache::Wyrd::Services::Index

Apache::Wyrd::Services::MySQLIndex

Apache::Wyrd::Site::Index

Apache::Wyrd::Site::MySQLIndex

Various index objects for site organization.

Apache::Wyrd::Page

Base Wyrd for Web site pages

LICENSE

Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.

See LICENSE under the documentation for Apache::Wyrd.