Data::Page(3pm)

1Data::Page(3)         User Contributed Perl Documentation        Data::Page(3)
2
3
4

NAME

6       Data::Page - help when paging through sets of results
7

SYNOPSIS

9         use Data::Page;
10
11         my $page = Data::Page->new();
12         $page->total_entries($total_entries);
13         $page->entries_per_page($entries_per_page);
14         $page->current_page($current_page);
15
16         print "         First page: ", $page->first_page, "\n";
17         print "          Last page: ", $page->last_page, "\n";
18         print "First entry on page: ", $page->first, "\n";
19         print " Last entry on page: ", $page->last, "\n";
20

DESCRIPTION

22       When searching through large amounts of data, it is often the case that
23       a result set is returned that is larger than we want to display on one
24       page. This results in wanting to page through various pages of data.
25       The maths behind this is unfortunately fiddly, hence this module.
26
27       The main concept is that you pass in the number of total entries, the
28       number of entries per page, and the current page number. You can then
29       call methods to find out how many pages of information there are, and
30       what number the first and last entries on the current page really are.
31
32       For example, say we wished to page through the integers from 1 to 100
33       with 20 entries per page. The first page would consist of 1-20, the
34       second page from 21-40, the third page from 41-60, the fourth page from
35       61-80 and the fifth page from 81-100. This module would help you work
36       this out.
37

METHODS

39       new
40
41       This is the constructor, which takes no arguments.
42
43         my $page = Data::Page->new();
44
45       There is also an old, deprecated constructor, which currently takes two
46       mandatory arguments, the total number of entries and the number of
47       entries per page. It also optionally takes the current page number:
48
49         my $page = Data::Page->new($total_entries, $entries_per_page, $current_page);
50
51       total_entries
52
53       This method get or sets the total number of entries:
54
55         print "Entries:", $page->total_entries, "\n";
56
57       entries_per_page
58
59       This method gets or sets the total number of entries per page (which
60       defaults to 10):
61
62         print "Per page:", $page->entries_per_page, "\n";
63
64       current_page
65
66       This method gets or sets the current page number (which defaults to 1):
67
68         print "Page: ", $page->current_page, "\n";
69
70       entries_on_this_page
71
72       This methods returns the number of entries on the current page:
73
74         print "There are ", $page->entries_on_this_page, " entries displayed\n";
75
76       first_page
77
78       This method returns the first page. This is put in for reasons of sym‐
79       metry with last_page, as it always returns 1:
80
81         print "Pages range from: ", $page->first_page, "\n";
82
83       last_page
84
85       This method returns the total number of pages of information:
86
87         print "Pages range to: ", $page->last_page, "\n";
88
89       first
90
91       This method returns the number of the first entry on the current page:
92
93         print "Showing entries from: ", $page->first, "\n";
94
95       last
96
97       This method returns the number of the last entry on the current page:
98
99         print "Showing entries to: ", $page->last, "\n";
100
101       previous_page
102
103       This method returns the previous page number, if one exists. Otherwise
104       it returns undefined:
105
106         if ($page->previous_page) {
107           print "Previous page number: ", $page->previous_page, "\n";
108         }
109
110       next_page
111
112       This method returns the next page number, if one exists. Otherwise it
113       returns undefined:
114
115         if ($page->next_page) {
116           print "Next page number: ", $page->next_page, "\n";
117         }
118
119       splice
120
121       This method takes in a listref, and returns only the values which are
122       on the current page:
123
124         @visible_holidays = $page->splice(\@holidays);
125
126       skipped
127
128       This method is useful paging through data in a database using SQL LIMIT
129       clauses. It is simply $page->first - 1:
130
131         $sth = $dbh->prepare(
132           q{SELECT * FROM table ORDER BY rec_date LIMIT ?, ?}
133         );
134         $sth->execute($date, $page->skipped, $page->entries_per_page);
135

NOTES

137       It has been said before that this code is "too simple" for CPAN, but I
138       must disagree. I have seen people write this kind of code over and over
139       again and they always get it wrong. Perhaps now they will spend more
140       time getting the rest of their code right...
141

AUTHOR

147       Based on code originally by Leo Lapworth, with many changes added by by
148       Leon Brocard <acme@astray.com>.
149

COPYRIGHT

151       Copyright (C) 2000-4, Leon Brocard
152
153       This module is free software; you can redistribute it or modify it
154       under the same terms as Perl itself.
155
156
157
158perl v5.8.8                       2004-10-28                     Data::Page(3)