1NAME
2 Data::Page - help when paging through sets of results
3
4SYNOPSIS
5 use Data::Page;
6
7 my $page = Data::Page->new();
8 $page->total_entries($total_entries);
9 $page->entries_per_page($entries_per_page);
10 $page->current_page($current_page);
11
12 print " First page: ", $page->first_page, "\n";
13 print " Last page: ", $page->last_page, "\n";
14 print "First entry on page: ", $page->first, "\n";
15 print " Last entry on page: ", $page->last, "\n";
16
17DESCRIPTION
18 When searching through large amounts of data, it is often the case that
19 a result set is returned that is larger than we want to display on one
20 page. This results in wanting to page through various pages of data. The
21 maths behind this is unfortunately fiddly, hence this module.
22
23 The main concept is that you pass in the number of total entries, the
24 number of entries per page, and the current page number. You can then
25 call methods to find out how many pages of information there are, and
26 what number the first and last entries on the current page really are.
27
28 For example, say we wished to page through the integers from 1 to 100
29 with 20 entries per page. The first page would consist of 1-20, the
30 second page from 21-40, the third page from 41-60, the fourth page from
31 61-80 and the fifth page from 81-100. This module would help you work
32 this out.
33
34METHODS
35 new
36 This is the constructor, which takes no arguments.
37
38 my $page = Data::Page->new();
39
40 There is also an old, deprecated constructor, which currently takes two
41 mandatory arguments, the total number of entries and the number of
42 entries per page. It also optionally takes the current page number:
43
44 my $page = Data::Page->new($total_entries, $entries_per_page, $current_page);
45
46 total_entries
47 This method get or sets the total number of entries:
48
49 print "Entries:", $page->total_entries, "\n";
50
51 entries_per_page
52 This method gets or sets the total number of entries per page (which
53 defaults to 10):
54
55 print "Per page:", $page->entries_per_page, "\n";
56
57 current_page
58 This method gets or sets the current page number (which defaults to 1):
59
60 print "Page: ", $page->current_page, "\n";
61
62 entries_on_this_page
63 This methods returns the number of entries on the current page:
64
65 print "There are ", $page->entries_on_this_page, " entries displayed\n";
66
67 first_page
68 This method returns the first page. This is put in for reasons of
69 symmetry with last_page, as it always returns 1:
70
71 print "Pages range from: ", $page->first_page, "\n";
72
73 last_page
74 This method returns the total number of pages of information:
75
76 print "Pages range to: ", $page->last_page, "\n";
77
78 first
79 This method returns the number of the first entry on the current page:
80
81 print "Showing entries from: ", $page->first, "\n";
82
83 last
84 This method returns the number of the last entry on the current page:
85
86 print "Showing entries to: ", $page->last, "\n";
87
88 previous_page
89 This method returns the previous page number, if one exists. Otherwise
90 it returns undefined:
91
92 if ($page->previous_page) {
93 print "Previous page number: ", $page->previous_page, "\n";
94 }
95
96 next_page
97 This method returns the next page number, if one exists. Otherwise it
98 returns undefined:
99
100 if ($page->next_page) {
101 print "Next page number: ", $page->next_page, "\n";
102 }
103
104 splice
105 This method takes in a listref, and returns only the values which are on
106 the current page:
107
108 @visible_holidays = $page->splice(\@holidays);
109
110 skipped
111 This method is useful paging through data in a database using SQL LIMIT
112 clauses. It is simply $page->first - 1:
113
114 $sth = $dbh->prepare(
115 q{SELECT * FROM table ORDER BY rec_date LIMIT ?, ?}
116 );
117 $sth->execute($date, $page->skipped, $page->entries_per_page);
118
119NOTES
120 It has been said before that this code is "too simple" for CPAN, but I
121 must disagree. I have seen people write this kind of code over and over
122 again and they always get it wrong. Perhaps now they will spend more
123 time getting the rest of their code right...
124
125SEE ALSO
126 Related modules which may be of interest: Data::Pageset,
127 Data::Page::Tied, Data::SpreadPagination.
128
129AUTHOR
130 Based on code originally by Leo Lapworth, with many changes added by by
131 Leon Brocard <acme@astray.com>.
132
133COPYRIGHT
134 Copyright (C) 2000-4, Leon Brocard
135
136 This module is free software; you can redistribute it or modify it under
137 the same terms as Perl itself.
138
139