NAME

Data::Pagination - Paginal navigation on some data

SYNOPSIS

  use Data::Pagination;

  # previously needs to check total number of entries. it can be
  # count of SQL records or length of array or something other.
  #
  # example: SELECT count(*) ...
  #
  # note: if no records exists, then no needs to continue processing.
  #       enough to tell the user about that.

  my $pg = Data::Pagination->new(
     $total_entries,    # - total number of entries (>= 1)
                        #
     $entries_per_page, # - how much records (>= 1) maximum you want
                        #   to see on one page.
                        #
     $pages_per_set,    # - how much pages you want to see in pages
                        #   set. if you don't want to use this
                        #   feature, then don't use, but some number
                        #   (>= 1) must be presented here.
                        #
     $current_page      # - user specified number of page from
                        #   request. must contain some integer
                        #   number (don't forget to check this).
  );

  # now, for getting slice of data, use properties from
  # "slice params" group.
  #
  # example: SELECT ...
  #          LIMIT $pg->{start_of_slice}, $pg->{length_of_slice}

  # all properties from "statistics" group are copied from arguments,
  # and with some properties from other groups can be used for
  # shown some statistic information to user.
  #
  # example:
  #
  #                 $pg->{total_pages}
  #                /   $pg->{total_entries}
  # Total pages: 20   /
  # Total records: 200
  # Shown from 61 to 70 records
  #              \     \
  #               \     $pg->{start_of_slice} + 1
  #                $pg->{end_of_slice} + 1
  #

  # properties from "pages control" and "pages set control" intended
  # for construction paginal navigation panel.
  #
  # example (simple):
  #
  #                   <-- previous page | next page -->
  #                         /                   \
  #                 $pg->{prev_page}       $pg->{next_page}
  #
  # example (advanced):
  #
  #                      $pg->{current_page}
  #                               |
  #         $pg->{prev_page}      |         $pg->{next_page}
  #                   \           |                /
  #           <<       <       6 [7] 8 9 10       >       >>
  #           /               /           \                \
  # $pg->{page_of_prev_set}  /             \  $pg->{page_of_next_set}
  #                         /               \
  #             $pg->{start_of_set}     $pg->{end_of_set}
  #
  #

DESCRIPTION

This class intended for organization of paginal navigation on some data. Basically intended for construction of paginal navigation panels on web sites.

METHODS

$pg = Data::Pagination->new($total_entries, $entries_per_page, $pages_per_set, $current_page)

Making all calculations and storing results at class properties.

Arguments:

$total_entries - total number of entries (>= 1)
$entries_per_page - number of entries per page (>= 1)
$pages_per_set - number of pages per set (>= 1)
$current_page - current number of page

Note: all arguments are required and must contains only integer numbers.

PROPERTIES

Slice params:

$pg->{start_of_slice} - start position of the slice (>= 0)
$pg->{end_of_slice} - end position of the slice (>= 0)
$pg->{length_of_slice} - length of the slice (>= 1)

Statistics:

$pg->{total_entries} - total number of entries (>= 1) (copied from arguments)
$pg->{entries_per_page} - number of entries per page (>= 1) (copied from arguments)
$pg->{pages_per_set} - number of pages per set (>= 1) (copied from arguments)

Pages control:

$pg->{total_pages} - total number of pages (>= 1)
$pg->{current_page} - current number of page (>= 1) (corrected)
$pg->{prev_page} - previous number of page (>= 1) or undefined, if haven't place to be
$pg->{next_page} - next number of page (>= 1) or undefined, if haven't place to be

Pages set control:

$pg->{start_of_set} - start position of current set (>= 1)
$pg->{end_of_set} - end position of current set (>= 1)
$pg->{page_of_prev_set} - nearest page number of the previous set (>= 1) or undefined, if haven't place to be
$pg->{page_of_next_set} - nearest page number of the next set (>= 1) or undefined, if haven't place to be

NOTES

Most simple way to check, needs to show navigation panel or not, is checking $pg->{total_pages} property. Needs only, if this property more then 1.
$pg->{prev_page}, $pg->{next_page}, $pg->{page_of_prev_set} and $pg->{page_of_next_set} properties must be checked for undefined value before using.
All results are in numbers, and you can construct paginal navigation panels with any design and can use templates processors (as TT and others). For that you only needs to transfer class object to template processor params.

AUTHOR

Andrian Zubko <ondr@cpan.org>

CPAN RT