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