1DBIx::Class::ResultSet:U:sPeargeCro(n3t)ributed Perl DocDuBmIexn:t:aCtliaosns::ResultSet::Pager(3)
2
3
4

NAME

6       DBIx::Class::ResultSet::Pager - help when paging through sets of
7       results
8

SYNOPSIS

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

DESCRIPTION

23       This module is a near-verbatim copy of Data::Page 2.02
24        <https://metacpan.org/pod/release/LBROCARD/Data-
25       Page-2.02/lib/Data/Page.pm>, which remained unchanged on CPAN from late
26       2009 through late 2019. The only differences are dropping a number of
27       accessor generators in lieu of direct method implementations, and the
28       incorporation of the lazily evaluated "total_entries" which was the
29       only part originally provided by DBIx::Class::ResultSet::Pager. This
30       module passes the entire contemporary test suite of Data::Page
31       unmodified.
32
33       WHAT FOLLOWS IS A VERBATIM COPY OF Data::Page's 2.02 DOCUMENTATION
34
35       When searching through large amounts of data, it is often the case that
36       a result set is returned that is larger than we want to display on one
37       page. This results in wanting to page through various pages of data.
38       The maths behind this is unfortunately fiddly, hence this module.
39
40       The main concept is that you pass in the number of total entries, the
41       number of entries per page, and the current page number. You can then
42       call methods to find out how many pages of information there are, and
43       what number the first and last entries on the current page really are.
44
45       For example, say we wished to page through the integers from 1 to 100
46       with 20 entries per page. The first page would consist of 1-20, the
47       second page from 21-40, the third page from 41-60, the fourth page from
48       61-80 and the fifth page from 81-100. This module would help you work
49       this out.
50

METHODS

52   new
53       This is the constructor, which takes no arguments.
54
55         my $page = DBIx::Class::ResultSet::Pager->new();
56
57       There is also an old, deprecated constructor, which currently takes two
58       mandatory arguments, the total number of entries and the number of
59       entries per page. It also optionally takes the current page number:
60
61         my $page = DBIx::Class::ResultSet::Pager->new($total_entries, $entries_per_page, $current_page);
62
63   total_entries
64       This method get or sets the total number of entries:
65
66         print "Entries:", $page->total_entries, "\n";
67
68   entries_per_page
69       This method gets or sets the total number of entries per page (which
70       defaults to 10):
71
72         print "Per page:", $page->entries_per_page, "\n";
73
74   current_page
75       This method gets or sets the current page number (which defaults to 1):
76
77         print "Page: ", $page->current_page, "\n";
78
79   entries_on_this_page
80       This methods returns the number of entries on the current page:
81
82         print "There are ", $page->entries_on_this_page, " entries displayed\n";
83
84   first_page
85       This method returns the first page. This is put in for reasons of
86       symmetry with last_page, as it always returns 1:
87
88         print "Pages range from: ", $page->first_page, "\n";
89
90   last_page
91       This method returns the total number of pages of information:
92
93         print "Pages range to: ", $page->last_page, "\n";
94
95   first
96       This method returns the number of the first entry on the current page:
97
98         print "Showing entries from: ", $page->first, "\n";
99
100   last
101       This method returns the number of the last entry on the current page:
102
103         print "Showing entries to: ", $page->last, "\n";
104
105   previous_page
106       This method returns the previous page number, if one exists. Otherwise
107       it returns undefined:
108
109         if ($page->previous_page) {
110           print "Previous page number: ", $page->previous_page, "\n";
111         }
112
113   next_page
114       This method returns the next page number, if one exists. Otherwise it
115       returns undefined:
116
117         if ($page->next_page) {
118           print "Next page number: ", $page->next_page, "\n";
119         }
120
121   splice
122       This method takes in a listref, and returns only the values which are
123       on the current page:
124
125         @visible_holidays = $page->splice(\@holidays);
126
127   skipped
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($page->skipped, $page->entries_per_page);
135
136   change_entries_per_page
137       This method changes the number of entries per page and the current page
138       number such that the first item on the current page will be present on
139       the new page.
140
141        $page->total_entries(50);
142        $page->entries_per_page(20);
143        $page->current_page(3);
144        print $page->first; # 41
145        $page->change_entries_per_page(30);
146        print $page->current_page; # 2 - the page that item 41 will show in
147

NOTES

149       It has been said before that this code is "too simple" for CPAN, but I
150       must disagree. I have seen people write this kind of code over and over
151       again and they always get it wrong. Perhaps now they will spend more
152       time getting the rest of their code right...
153
154       Based on code originally by Leo Lapworth, with many changes added by by
155       Leon Brocard <acme@astray.com>, and few enhancements by James Laver
156       (ELPENGUIN)
157

FURTHER QUESTIONS?

159       Check the list of additional DBIC resources.
160
162       This module is free software copyright by the DBIx::Class (DBIC)
163       authors. You can redistribute it and/or modify it under the same terms
164       as the DBIx::Class library.
165
166
167
168perl v5.38.0                      2023-07-20  DBIx::Class::ResultSet::Pager(3)
Impressum