c490e2ab6dfb088db28b8bde99c79510bbc30a41
[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);
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->{cur}    = $page < 1 ? 1
21                  : $page > $ret->{max} ? $ret->{max}
22                  : $page;
23   $ret->{common} = make_common_pages($ret->{cur}, $ret->{max});
24
25   $params{args}{page}     = $ret->{cur};
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 1;
68
69 __END__
70
71 =encoding utf-8
72
73 =head1 NAME
74
75 SL::Helper::Paginated - Manager mixin for paginating results.
76
77 =head1 SYNOPSIS
78
79 In the manager:
80
81   use SL::Helper::Paginated;
82
83   __PACKAGE__->default_objects_per_page(10); # optional, defaults to 20
84
85 In the controller:
86
87   my %args = (
88     query => [ id         => $params{list_of_selected_ids},
89                other_attr => $::form->{other_attr}, ],
90   );
91
92   $self->{pages}   = SL::DB::Manager::MyObject->paginate(args => \%args, page => $::form->{page});
93   $self->{objects} = SL::DB::Manager::MyObject->get_all(%args);
94
95 In the template:
96
97   [% PROCESS 'common/paginate.html'
98     pages=SELF.pages
99     base_url=L.url_for(action='list', ...)
100   %]
101
102 =head1 FUNCTIONS
103
104 =over 4
105
106 =item C<paginate> args => HREF, page => $page, [ per_page => $per_page ]
107
108 Paginate will prepare information to be used for paginating, change the given
109 args to use them, and return a data structure containing information for later
110 display.
111
112 C<args> needs to contain a reference to a hash, which will be used as an
113 argument for C<get_all>. After C<paginate> the keys C<page> and C<per_page>
114 will be set. The keys C<limit> and C<offset> will be unset, should they exist,
115 since they don't make sense with paginating.
116
117 C<page> should contain a value between 1 and the maximum pages. Will be
118 sanitized.
119
120 The parameter C<per_page> is optional. If not given the default value of the
121 Manager will be used.
122
123 =back
124
125 =head1 TEMPLATE HELPERS
126
127 =over 4
128
129 =item C<common/paginate.html> pages=SELF.pages, base_url=URL
130
131 The template will render a simple list of links to the
132 various other pages. A C<base_url> must be given for the links to work.
133
134 =back
135
136 =head1 BUGS
137
138 None yet.
139
140 =head1 AUTHOR
141
142 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>
143
144 =cut