File Coverage

blib/lib/Class/DBI/Plugin/DeepAbstractSearchPager.pm

Criterion	Covered	Total	%
statement	27	98	27.5
branch	2	50	4.0
condition	0	35	0.0
subroutine	7	13	53.8
pod	3	4	75.0
total	39	200	19.5

package Class::DBI::Plugin::DeepAbstractSearchPager;
use strict;
use warnings;
use Carp;

use UNIVERSAL::require;
use base qw( Data::Page Class::Data::Inheritable );

our $VERSION = 0.04;

# D::P inherits from Class::Accessor::Chained::Fast
__PACKAGE__->mk_accessors( qw( where abstract_attr per_page page order_by _cdbi_app ) );

__PACKAGE__->mk_classdata( '_syntax' );
__PACKAGE__->mk_classdata( '_deep_pager_class' );


=head1 NAME

Class::DBI::Plugin::DeepAbstractSearchPager - paged queries for CDBI::Plugin::DeepAbstractSearch

=head1 DESCRIPTION

Adds a deep_pager method to your class that can query using SQL::Abstract where clauses
with joined table fields as described by C,
and limit the number of rows returned to a specific subset.

=head1 SYNOPSIS

    package CD;
    use base 'Class::DBI';

    use Class::DBI::Plugin::DeepAbstractSearch;      # pager needs this
    use Class::DBI::Plugin::DeepAbstractSearchPager;

    # or to use a different syntax
    # use Class::DBI::Plugin::Pager::RowsTo;

    __PACKAGE__->set_db(...);


    # in a nearby piece of code...

    use CD;

    # see SQL::Abstract for how to specify the query
    my $where = { 'artist.name' => { -like => '%Elvis%' } };

    my $order_by => 'artist.name, title';

    # bit by bit:
    my $pager = CD->deep_pager;

    $pager->per_page( 10 );
    $pager->page( 3 );
    $pager->where( $where );
    $pager->order_by( $order_by );

    $pager->set_syntax( 'RowsTo' );

    my @cds = $pager->deep_search_where;

    # or all at once
    my $pager = CD->deep_pager( $where, $order_by, 10, 3 );

    my @cds = $pager->deep_search_where;

    # or

    my $pager = CD->deep_pager;

    my @cds = $pager->deep_search_where( $where, $order_by, 10, 3 );

    # $pager isa Data::Page
    # @cds contains the CDs just for the current page

=head1 METHODS

=over

=item import

Loads the C method into the CDBI app.

=cut

sub import {
    my ( $class ) = @_; # the pager class or subclass

    __PACKAGE__->_deep_pager_class( $class );

    my $caller;

    # find the app
    foreach my $level ( 0 .. 10 )
    {
        $caller = caller( $level );
        last if UNIVERSAL::isa( $caller, 'Class::DBI' )
    }

    croak( "can't find the CDBI app" ) unless $caller;

	no strict 'refs';
    *{"$caller\::deep_pager"} = \&deep_pager;
}


=item pager( [$where, [$abstract_attr]], [$order_by], [$per_page], [$page], [$syntax] )

Also accepts named arguments:

    where           => $where,
    abstract_attr   => $attr,
    order_by        => $order_by,
    per_page        => $per_page,
    page            => $page,
    syntax          => $syntax

Returns a pager object. This subclasses L.

Note that for positional arguments, C<$abstract_attr> can only be passed if
preceded by a C<$where> argument.

C<$abstract_attr> can contain the C<$order_by> setting (just as in
L).

=over 4

=item configuration

The named arguments all exist as get/set methods.

=over 4

=item where

A hashref specifying the query. See L.

=item abstract_attr

A hashref specifying extra options to be passed through to the
L constructor.

=item order_by

Single column name, string of column names or array ref of column names
for the ORDER BY clause.  Defaults to the primary key(s) if not set.

=item per_page

Number of results per page.

=item page

The pager will retrieve results just for this page. Defaults to 1.

=item syntax

Change the way the 'limit' clause is constructed. See C. Default
is C.

=back

=back

=cut

sub deep_pager
{
    my $cdbi = shift;

    my $class = __PACKAGE__->_deep_pager_class;

    my $self = bless {}, $class;

    $self->_cdbi_app( $cdbi );

    # This has to come before _init, so the caller can choose to set the syntax
    # instead. But don't auto-set if we're a subclass.
    $self->auto_set_syntax if $class eq __PACKAGE__;

    $self->_init( @_ );

    return $self;
}

# _init is also called by results, so preserve any existing settings if
# new settings are not provided
sub _init {
    my $self = shift;

    return unless @_;

    my ( $where, $abstract_attr, $order_by, $per_page, $page, $syntax );

    if ( ref( $_[0] ) or $_[0] =~ /^\d+$/ )
    {
        $where          = shift if ref $_[0] eq 'HASH';
        $abstract_attr  = shift if ref $_[0] eq 'HASH';
        $order_by       = shift unless $_[0] =~ /^\d+$/;
        $per_page       = shift if $_[0] && $_[0] =~ /^\d+$/;
        $page           = shift if $_[0] && $_[0] =~ /^\d+$/;
        $syntax         = shift;
    }
    else
    {
        my %args  = @_;

        $where          = $args{where};
        $abstract_attr  = $args{abstract_attr};
        $order_by       = $args{order_by};
        $per_page       = $args{per_page};
        $page           = $args{page};
        $syntax         = $args{syntax};
    }

    $order_by = delete $$abstract_attr{order_by} if ($abstract_attr and !$order_by);

    $self->per_page( $per_page )          if $per_page;
    $self->set_syntax( $syntax )          if $syntax;
    $self->abstract_attr( $abstract_attr )if $abstract_attr;
    $self->where( $where )                if $where;
    $self->order_by( $order_by )          if $order_by;
    $self->page( $page )                  if $page;
}

=item deep_search_where

Retrieves results from the pager. Accepts the same arguments as the C
method.

=cut

# like CDBI::Plugin::DeepAbstractSearch::deep_search_where, with extra limitations
sub deep_search_where {
    my $self = shift;

    $self->_init( @_ );

    $self->_setup_pager;

    my $cdbi = $self->_cdbi_app;

    my ($what, $from, $where, $bind) = $cdbi->get_deep_where($self->where,
    	{ order_by => $self->order_by || [ $cdbi->primary_columns ] } );

    my $syntax        = $self->_syntax || $self->set_syntax;
    my $limit_phrase  = $self->$syntax;

	my $sql = <<"";
SELECT $what
FROM $from
WHERE $where
$limit_phrase

	return $cdbi->sth_to_objects($cdbi->sql_deeply_and_broadly($sql), $bind);
}

sub _setup_pager {
    my ( $self ) = @_;

    my $where    = $self->where    || croak( 'must set a query before retrieving results' );
    my $per_page = $self->per_page || croak( 'no. of entries per page not specified' );
    my $cdbi     = $self->_cdbi_app;
    my $count    = $cdbi->count_deep_search_where( $where );
    my $page     = $self->page || 1;

    $self->total_entries( $count );
    $self->entries_per_page( $per_page );
    $self->current_page( $page );

    croak( 'Fewer than one entry per page!' ) if $self->entries_per_page < 1;

    $self->current_page( $self->first_page ) unless defined $self->current_page;
    $self->current_page( $self->first_page ) if $self->current_page < $self->first_page;
    $self->current_page( $self->last_page  ) if $self->current_page > $self->last_page;
}

=item set_syntax( [ $name || $class || $coderef ] )

Changes the syntax used to generate the C or other phrase that restricts
the results set to the required page.

The syntax is implemented as a method called on the pager, which can be
queried to provide the C<$rows> and C<$offset> parameters (see the subclasses
included in this distribution).

=over 4

=item $class

A class with a C method.

=item $name

Name of a class in the C namespace, which has a
C method.

=item $coderef

Will be called as a method on the pager object, so receives the pager as its
argument.

=item (no args)

Called without args, will default to C, which causes
L
to be used.

=back

=cut

sub set_syntax {
    my ( $proto, $syntax ) = @_;

    # pick up default from subclass, or load from LimitOffset
    $syntax ||= $proto->can( 'make_limit' );
    $syntax ||= 'LimitOffset';

    if ( ref( $syntax ) eq 'CODE' )
    {
        $proto->_syntax( $syntax );
        return $syntax;
    }

    my $format_class = $syntax =~ '::' ? $syntax : "Class::DBI::Plugin::Pager::$syntax";

    $format_class->require || croak "error loading $format_class: $UNIVERSAL::require::ERROR";

    my $formatter = $format_class->can( 'make_limit' ) || croak "no make_limit method in $format_class";

    $proto->_syntax( $formatter );

    return $formatter;
}

=item auto_set_syntax

This is called automatically when you call C, and attempts to set the
syntax automatically.

If you are using a subclass of the pager, this method will not be called.

Will C if using Oracle or DB2, since there is no simple syntax for limiting
the results set. DB2 has a C keyword, but that seems to apply to a
cursor and I don't know if there is a cursor available to the pager. There
should probably be others to add to the unsupported list.

Supports the following drivers:

                      DRIVER        CDBI::P::Pager subclass
    my %supported = ( pg        => 'LimitOffset',
                      mysql     => 'LimitOffset', # older versions need LimitXY
                      sqlite    => 'LimitOffset', # or LimitYX
                      interbase => 'RowsTo',
                      firebird  => 'RowsTo',
                      );

Older versions of MySQL should use the LimitXY syntax. You'll need to set it
manually, either by C, or by passing
C 'LimitXY'> to a method call, or call C directly.

Any driver not in the supported or unsupported lists defaults to LimitOffset.

Any additions to the supported and unsupported lists gratefully received.

=cut

sub auto_set_syntax {
    my ( $self ) = @_;

    # not an exhaustive list
    my %not_supported = ( oracle => 'Oracle',
                          db2    => 'DB2',
                          );

    # additions welcome
    my %supported = ( pg        => 'LimitOffset',
                      mysql     => 'LimitOffset', # older versions need LimitXY
                      sqlite    => 'LimitOffset', # or LimitYX
                      interbase => 'RowsTo',
                      firebird  => 'RowsTo',
                      );

    my $cdbi = $self->_cdbi_app;

    my $driver = lc( $cdbi->__driver );

    die __PACKAGE__ . " can't build limit clauses for $not_supported{ $driver }"
        if $not_supported{ $driver };

    $self->set_syntax( $supported{ $driver } || 'LimitOffset' );
}

1;

__END__