Massenerstellen von RG aus LS: geschlossene LS nicht (erneut) verarbeiten
[kivitendo-erp.git] / SL / DB / Helper / Paginated.pm
1 package SL::DB::Helper::Paginated;
2
3 use strict;
4
5 require Exporter;
6 our @ISA    = qw(Exporter);
7 our @EXPORT = qw(paginate disable_paginating);
8
9 use List::MoreUtils qw(any);
10
11 sub paginate {
12   my ($self, %params)     = @_;
13   my $page                = $params{page} || 1;
14   my %args                = %{ $params{args} || {} };
15
16   my $ret                 = { };
17
18   $ret->{per_page}        = per_page($self, %params);
19   $ret->{max}             = ceil($self->get_all_count(%args), $ret->{per_page}) || 1;
20   $ret->{page}            = $page < 1 ? 1
21                           : $page > $ret->{max} ? $ret->{max}
22                           : $page;
23   $ret->{common}          = make_common_pages($ret->{page}, $ret->{max});
24
25   $params{args}{page}     = $ret->{page};
26   $params{args}{per_page} = $ret->{per_page};
27   delete $params{args}{limit};
28   delete $params{args}{offset};
29
30   return $ret;
31 }
32
33 sub per_page {
34   my ($self, %params) = @_;
35
36   return $params{per_page} if exists $params{per_page};
37   return $self->default_objects_per_page;
38 }
39
40 sub ceil {
41   my ($a, $b) = @_;
42   use integer;
43
44   return 1 unless $b;
45   return $a / $b + ($a % $b ? 1 : 0);
46 }
47
48 sub make_common_pages {
49   my ($cur, $max) = @_;
50   return [
51     map {
52       active  => $_ != $cur,
53       page    => $_,
54       visible => calc_visibility($cur, $max, $_),
55     }, 1 .. $max
56   ];
57 }
58
59 sub calc_visibility {
60   my ($cur, $max, $this) = @_;
61   any { $_ } abs($cur - $this) < 5,
62              $this <= 3,
63              $this == $max,
64              any { abs ($cur - $this) == $_ } 10, 50, 100, 500, 1000, 5000;
65 }
66
67 sub disable_paginating {
68   my ($self, %params) = @_;
69
70   delete $params{args}{page};
71   delete $params{args}{per_page};
72 }
73
74 1;
75
76 __END__
77
78 =encoding utf-8
79
80 =head1 NAME
81
82 SL::DB::Helper::Paginated - Manager mixin for paginating results.
83
84 =head1 SYNOPSIS
85
86 In the manager:
87
88   use SL::DB::Helper::Paginated;
89
90   __PACKAGE__->default_objects_per_page(10); # optional, defaults to 20
91
92 In the controller:
93
94   my %args = (
95     query => [ id         => $params{list_of_selected_ids},
96                other_attr => $::form->{other_attr}, ],
97   );
98
99   $self->{pages}   = SL::DB::Manager::MyObject->paginate(args => \%args, page => $::form->{page});
100   $self->{objects} = SL::DB::Manager::MyObject->get_all(%args);
101
102 In the template:
103
104   [% PROCESS 'common/paginate.html'
105     pages=SELF.pages
106     base_url=L.url_for(action='list', ...)
107   %]
108
109 =head1 FUNCTIONS
110
111 =over 4
112
113 =item C<paginate> args => HREF, page => $page, [ per_page => $per_page ]
114
115 Paginate will prepare information to be used for paginating, change the given
116 args to use them, and return a data structure containing information for later
117 display. See L<STRUCTURE OF PAGES> for information how the return is formatted.
118
119 C<args> needs to contain a reference to a hash, which will be used as an
120 argument for C<get_all>. After C<paginate> the keys C<page> and C<per_page>
121 will be set. The keys C<limit> and C<offset> will be unset, should they exist,
122 since they don't make sense with paginating.
123
124 C<page> should contain a value between 1 and the maximum pages. Will be
125 sanitized.
126
127 The parameter C<per_page> is optional, otherwise the default value of the
128 Manager will be used.
129
130 =back
131
132 =head1 STRUCTURE OF PAGES
133
134 The returned hashref will have the following structure:
135
136   { per_page => 20,   # how many entries per page
137     max      => 5,    # number of the last page
138     page     => 2,    # number of the current page
139     common   => [     # an array of hashes for each page
140       ...,
141       { active  => 1, # set if this is the active page
142         page    => 2, # the string to display for this page
143         visible => 1, # should this be displayed in the paginating controls
144       },
145       ...
146     ]
147   }
148
149 You may assume that C<page> is sanitized to be within 1..C<max>.
150
151 The common list is kept arbitrary by design, so that the algorithm to display
152 the paginating controls can be changed by solely changing the
153 C<make_common_pages> algorithm. If you need different glyphs for the pages or
154 different boundaries, translate the C<page> entry for the page.
155
156 The initial algorithm will show the following pages:
157
158 =over 4
159
160 =item *
161
162 1, 2, 3
163
164 =item *
165
166 Last page
167
168 =item *
169
170 Current page +/- 5 pages
171
172 =item *
173
174 Current page +/- 10, 50, 100, 500, 1000, 5000
175
176 =back
177
178 =head1 TEMPLATE HELPERS
179
180 =over 4
181
182 =item C<common/paginate.html> pages=SELF.pages, base_url=URL
183
184 The template will render a simple list of links to the
185 various other pages. A C<base_url> must be given for the links to work.
186
187 =back
188
189 =head1 BUGS
190
191 None yet.
192
193 =head1 AUTHOR
194
195 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>
196
197 =cut