File Coverage

lib/Data/Scroller.pm

Criterion	Covered	Total	%
statement	129	138	93.4
branch	18	34	52.9
condition	11	25	44.0
subroutine	25	25	100.0
pod	8	8	100.0
total	191	230	83.0

package Data::Scroller;
use strict;
use warnings;
use vars qw( $VERSION @ISA );
$VERSION = '1.00';

# =============================================================================
# params for use in templates.
# =============================================================================
use constant PARAM_PAGE_LIST        => "page_list";
use constant PARAM_PAGE_NEXT       	=> "page_next";
use constant PARAM_PAGE_PREV       	=> "page_prev";
use constant PARAM_PAGE_FIRST     	=> "page_first";
use constant PARAM_PAGE_LAST     	  => "page_last";
use constant PARAM_PAGE_NAME        => "page_name";
use constant PARAM_PAGE_TOTAL       => "page_total";
use constant PARAM_PAGE_INCREMENT   => "page_increment";

# =============================================================================
# default input parameters.
# =============================================================================
use constant PAGING_INCREMENT       => 10; # default paging increment
use constant PAGING_NAME            => "row_num"; # default paging name

# ----------------------------------------------------------------------
# constructor - takes hash of paramaters
# ----------------------------------------------------------------------
sub new
{
  my $class = shift;
  my $self = {};
  bless($self, $class);
  return undef if !$self->_init(@_);
  return $self;
}

# ----------------------------------------------------------------------
# return hashref of parameters for use in templates
# ----------------------------------------------------------------------
sub display
{
	my $self = shift;

  my $params = $self->{params};
	my $max_value = $self->{max_value};
	my $max_display = $self->{max_display};
	my $name = $self->{name};
	my $increment	= $self->{increment};
	my $selected = $self->{selected};
	my $page_increment = $self->{page_increment};

	# ----------------------------------------------------------------------
  # paging not required
	# ----------------------------------------------------------------------
  return $params if $max_value <= $increment;

	# ----------------------------------------------------------------------
	# what should the page number be for the results the user has selected?
	# ----------------------------------------------------------------------
  my $start = 1;
	$start = $self->_round($selected / $page_increment) if $selected > 0;

	# ----------------------------------------------------------------------
	# set the start and end points for display from the current page number..
	# ----------------------------------------------------------------------
	my $set_start = 1;
	my $set_end = $page_increment;
	($set_start, $set_end) = $self->_page_inc_by_one($set_start, $set_end, $start, $page_increment);

	# ----------------------------------------------------------------------
	# display extra <$page_increment> results if the selected page is the first
  # or last in a set..
	# ----------------------------------------------------------------------
	if ($start == $set_end and $set_end < $max_display) {
		$set_end += $page_increment;
	}
	elsif ($start == $set_start and $set_start >= $page_increment) {
		$set_start = ($set_start - $page_increment);
	}

	my $next = $increment;

	my @list = ();
	my $value = 0;
	my $prev = 0;
	for (my $i = $set_start; $i <= $set_end; $i++) {
		$value = ($i - 1) * $increment;
		last if ($value >= $max_value);

		my $item = {
			page_display  => $i,
			page_value    => $value,
		};

		if ($selected == $value) {
			$item->{page_current} = 1;
			$next += $value;
			if ($value > 0) {
				$prev = $value - $increment;
			}
		}
		push @list, $item;
	}

	$params->{+PARAM_PAGE_LIST} = \@list;
  $params->{+PARAM_PAGE_NAME} = $name;
  $params->{+PARAM_PAGE_TOTAL} = $max_display;
  $params->{+PARAM_PAGE_INCREMENT} = $increment;

	my $page_last = $self->_round(($max_display * $increment) - $increment);
  unless (($selected == $page_last)) {
    $params->{+PARAM_PAGE_LAST} = $page_last;
  }

	if ($next < $max_value) {
		$params->{+PARAM_PAGE_NEXT} = $next;
	}

	if ($selected > 0) {
    $params->{+PARAM_PAGE_FIRST} = 0;
		$params->{+PARAM_PAGE_PREV} = $prev;
	}

  return $params;
}

# ----------------------------------------------------------------------
# get methods to retrieve object properties as required
# ----------------------------------------------------------------------
sub max_value { shift->{max_value} }
sub increment { shift->{increment} }
sub max_display { shift->{max_display} }
sub name { shift->{name} }
sub selected { shift->{selected} }
sub page_increment { shift->{page_increment} }

# ----------------------------------------------------------------------
# work out what the paging menu display start and end points are
# for the selected page.
# this routine uses a base increment of $page_increment, then
# increments that by one in either direction, aka google style.
# ----------------------------------------------------------------------
sub _page_inc_by_one
{
  my $self = shift;
	my ($set_start, $set_end, $start, $inc) = @_;

	if ($start <= $inc) {
		$set_end = ($start + $inc) - 1;
	}
	elsif ($start > $inc and $set_end < (($start + $inc) - 1)) {
		$set_end++;
		$set_end = $self->_page_inc_by_one($set_start, $set_end, $start, $inc);
	}

	if ($start < ($inc + 1)) {
		$set_start = 1;
	}
	else {
		$set_start = ($set_end - $inc) + 1;
	}

	return ($set_start, $set_end);
}

# ----------------------------------------------------------------------
# round UP
# ----------------------------------------------------------------------
sub _round
{
  my ($self, $val) = @_;
  return ($val == int($val) ? $val : int($val + 1));
}

# ----------------------------------------------------------------------
# initialize paging object properties
# ----------------------------------------------------------------------
sub _init
{
  my ($self, %args) = @_;

	my $max_value = $args{max_value} || die "max_value is required"; # total records / rows
	my $increment = $args{increment} || PAGING_INCREMENT; # records to display per page
	my $max_display = $args{max_display}; # max pages to display. TODO: not yet user option
	if (!defined($max_display) || !length($max_display)) {
		# $max_display = int($max_value / $increment) + 1; # ref display page numbers
		$max_display = $self->_round(($max_value / $increment));
	}
	my $name = $args{name} || $self->PAGING_NAME;
  my $selected = $args{selected};
  if (!defined($selected) || $selected !~ /\d+/) {
    $selected = 0; # current page, default 0 = page 1
  }
  # the number of pages to increment in either direction by when incrementing paging display
  my $page_increment = $args{page_increment} || $increment;

  my $params = $self->_init_params;

  $self->{max_value} = $max_value;
  $self->{increment} = $increment;
  $self->{max_display} = $max_display;
  $self->{name} = $name;
  $self->{selected} = $selected;
	$self->{page_increment} = $page_increment;
  $self->{params} = $params;
  $self->{initialized} = 1;

  return 1;
}

# ----------------------------------------------------------------------
# initialize the params hash ref containing the template variables
# ----------------------------------------------------------------------
sub _init_params
{
  my $self = shift;
  my $params = {};
	$params->{+PARAM_PAGE_LIST} = undef;
  $params->{+PARAM_PAGE_NAME} = undef;
  $params->{+PARAM_PAGE_TOTAL} = undef;
  $params->{+PARAM_PAGE_INCREMENT} = undef;
  $params->{+PARAM_PAGE_LAST} = undef;
  $params->{+PARAM_PAGE_NEXT} = undef;
  $params->{+PARAM_PAGE_FIRST} = undef;
  $params->{+PARAM_PAGE_PREV} = undef;
  return $params;
}

1;

__END__