/ 
Data-SimplePaginator-0.5
River stage zero No dependents
++
 / Data::SimplePaginator
Jonathan Buhacoff

NAME

Data::SimplePaginator - data pagination without assumptions (I think)

SYNOPSIS

 my $paginator;
 # paginate the alphabet into groups of 10 letters each
 $paginator = Data::SimplePaginator->new(10);
 $paginator->data(A..Z);
 
 # print the second page (K..T)
 foreach( $paginator->page(2) ) {
        print $_;
 }

DESCRIPTION

This module helps me create pagination without a lot of fuss. I looked at other pagination modules (see also, below) and their interfaces were cumbersome for me.

This module will NOT...

Keep track of the current page for you
Screw with your CGI or other environment
Generate any HTML

If you're using Template Toolkit you probably want to use Data::Pageset or Data::SpreadPagination because they have lots of subs that work great with the way TT is set up.

METHODS

new

 my $number_per_page = 10;
 
 $paginator = Data::SimplePaginator->new();
 
 $paginator = Data::SimplePaginator->new($number_per_page);
 
 $paginator = Data::SimplePaginator->new($number_per_page, A..Z);

Creates a new pagination object to split up data into sets of $number_per_page. Default items per page is 10, and default data is the empty list.

data

 my @items = ('orange','apple','banana','...');
 $paginator->data( @items );
 
 my @all = $paginator->data;

This method lets you set new data items for the paginator. It stores a shallow copy of the array, not a reference to it.

Return value is the current data array.

size

 $paginator->size(15);
 
 my $items_per_page = $paginator->size;

This method lets you set the size of the page, a.k.a. the number of items per page.

Return value is the size of the page.

pages

 my $number_of_pages = $paginator->pages;

Returns the number of pages based on the data you provide and the number of items per page that you set.

page

 my @contents = $paginator->page($number);

 my @first_page = $paginator->page(1);
 
 my @last_page = $paginator->page( $paginator->pages );

The first page is page 1, the last page is number of pages.

Returns items from @list that are on the specified page. If you give an invalid/undefined page number or one that's out of range for your data set, you get an empty list.

EXAMPLES

use Data::SimplePaginator;

paginate the alphabet into groups of 10 letters each

 $paginator = Data::SimplePaginator->new(10,A..Z);
 print "first page: ". join(" ", $paginator->page(1)) . "\n";

print every page

 foreach my $page ( 1..$paginator->pages ) {
   print "page $page: ". join(" ", $paginator->page($page)) . "\n";
 }
 print "last page: ". join(" ", $paginator->page($paginator->pages)) . "\n";

add more elements to the paginator

 $paginator->data( $paginator->data, 1..4, map { lc } A..Z, 5..8 );

create a pageset paginator to group pages in sets of 3

 my $pageset = Data::SimplePaginator->new(3, 1..$paginator->pages);
 
 foreach my $setnum ( 1..$pageset->pages ) {
   print "pageset $setnum\n";
   foreach my $page ( $pageset->page($setnum) ) {
     print "  page $page: ". join(" ", $paginator->page($page)) . "\n";
   }
 }

print every page, grouping into pagesets, resetting page numbers

 foreach my $setnum ( 1..$pageset->pages ) {
   print "pageset $setnum\n";
   foreach my $page ( 1..$pageset->page($setnum) ) {
     print "  page $page: ". join(" ", $paginator->page( ($pageset->page($setnum))[$page-1])) . "\n";
   }
 }

SEE ALSO

The other paginators I looked at before deciding to write this one:

HTML::Paginator
Data::Paginated
Data::Page (also: Data::Pageset, Data::SpreadPagination)

AUTHOR

Jonathan Buhacoff <jonathan@buhacoff.net>

COPYRIGHT

Copyright (C) 2004-2008 Jonathan Buhacoff. All rights reserved.

LICENSE

This library is free software and can be modified and distributed under the same terms as Perl itself.