File Coverage

blib/lib/CGI/Pager.pm

Criterion	Covered	Total	%
statement	49	86	56.9
branch	10	30	33.3
condition	4	17	23.5
subroutine	12	22	54.5
pod	16	17	94.1
total	91	172	52.9

package CGI::Pager;

use 5.008;
use strict;
use warnings;

use URI;
use URI::QueryParam;


our $VERSION = '1.00';


sub new {
   ## The constructor
   my $proto = shift;

   my $self = bless {
      url              => $ENV{REQUEST_URI},
      offset_param     => 'offset',
      hide_zero_offset => 1,
      page_len         => 20,
      labels => {
         first => 'First',
         last  => 'Last',
         next  => 'Next',
         prev  => 'Previous',
      },
      links_order => [ qw/first prev pages next last/ ],
      links_delim => '   ',
      pages_delim => '  ',
      @_,
   }, $proto;

   $self->{URI} = URI->new($self->{url});
   $self->{offset} = $self->{URI}->query_param($self->{offset_param}) || 0;

   return $self;
}


sub url_for_offset {
   ## Returns URL for the given offset.
   my $self = shift;
   my ($offset) = @_;

   return undef unless defined $offset;

   my $work_uri = $self->{URI}->clone;

   if ($offset == 0 && $self->{hide_zero_offset}) {
      $work_uri->query_param_delete($self->{offset_param});
   }
   else {
      $work_uri->query_param($self->{offset_param} => $offset);
   }

   return $work_uri;
}


sub total_count {
   ## Return total count of results, as set on initialization.
   my $self = shift;

   return $self->{total_count};
}


sub is_at_start {
   ## Returns true if the pager is at the start of recordset.
   my $self = shift;

   return !$self->{offset};
}


sub is_at_end {
   ## Returns true if the pager is at the end of recordset.
   my $self = shift;

   return $self->{offset} + $self->{page_len} >= $self->{total_count};
}


sub next_offset {
   ## Returns offset for the next page.
   my $self = shift;

   return $self->is_at_end ? undef : $self->{offset} + $self->{page_len};
}


sub prev_offset {
   ## Returns offset for the previous page.
   my $self = shift;

   return undef if $self->is_at_start;

   my $prev_offset = $self->{offset} - $self->{page_len};
   $prev_offset = 0 if $prev_offset < 0;

   return $prev_offset;
}


sub last_offset {
   ## Returns offset for the last page.
   my $self = shift;

   my $last_page_len = ($self->{total_count} % $self->{page_len})
                       || $self->{page_len};
   my $last_offset = $self->{total_count} - $last_page_len;
   $last_offset = 0 if $last_offset < 0;

   return $last_offset;
}


sub first_pos_displayed {
   ## Returns position of the first row currently displayed.
   my $self = shift;

   return $self->{offset} + 1;
}


sub last_pos_displayed {
   ## Returns position of the last row currently displayed.
   my $self = shift;

   my $result = $self->{offset} + $self->{page_len};
   $result = $self->{total_count} if $result > $self->{total_count};

   return $result;
}


sub prev_url {
   ## Returns URL for the previous page as URI object.
   my $self = shift;

   return $self->url_for_offset($self->prev_offset);
}


sub next_url {
   ## Returns URL for the next page as URI object.
   my $self = shift;

   return $self->url_for_offset($self->next_offset);
}


sub first_url {
   ## Returns URL for the first page as URI object.
   my $self = shift;

   return $self->url_for_offset(0);
}


sub last_url {
   ## Returns URL for the last page as URI object.
   my $self = shift;

   return $self->url_for_offset($self->last_offset);
}


sub pages {
   ## Returns reference to an array of hashes representing pages in
   ## the result set.
   my $self = shift;

   unless ($self->{pages}) {

      my $offset = 0;
      my $page_num = 1;

      do {
         push @{ $self->{pages} }, {
            url        => $self->url_for_offset($offset),
            number     => $page_num,
            offset     => $offset,
            is_current => $offset == $self->{offset},
         };

         $offset += $self->{page_len};
         $page_num++;

      } while ($offset < $self->{total_count});
   }

   return wantarray ? @{ $self->{pages} } : $self->{pages};
}


sub html {
   ## Returns HTML for specified part(s) of navigation.
   my $self = shift;
   my ($format) = @_;

   if ($format eq 'combined_div') {
      return @{ $self->pages } > 1 ?
                '' . $self->html('combined') . '' : '';
   }
   elsif ($format eq 'combined') {
      return join $self->{links_delim},
                  grep defined,
                       map $self->html($_),
                           @{ $self->{links_order} };
   }
   elsif ($format eq 'pages') {
      return join $self->{pages_delim},
                  map $_->{is_current} ?
                         "$_->{number}" :
                         "{url}\">$_->{number}",
                      $self->pages;
   }
   else {
      return undef if $format =~ /^(first|prev)$/ && $self->is_at_start
                      || $format =~ /^(last|next)$/ && $self->is_at_end;
      my $url_method = "${format}_url";
      return '$self->{labels}{$format}";
   }
}


sub quick_html {
   ## Returns HTML generated by automatically created pager instance.
   ## Designed to be called as function instead of OO interface.
   my %params = @_;

   my $html_mode = delete $params{html_mode};
   my $pager = __PACKAGE__->new(%params);
   return $pager->html($html_mode);
}


1;


__END__