1 package SL::Controller::Helper::Paginated;
5 use Exporter qw(import);
6 our @EXPORT = qw(make_paginated get_paginate_spec get_current_paginate_params _save_current_paginate_params _get_models_handler_for_paginated _callback_handler_for_paginated disable_pagination);
8 use constant PRIV => '__paginatedhelper_priv';
10 use List::Util qw(min);
12 my %controller_paginate_spec;
15 my ($class, %specs) = @_;
17 $specs{MODEL} ||= $class->controller_name;
18 $specs{MODEL} =~ s{ ^ SL::DB:: (?: .* :: )? }{}x;
19 $specs{PER_PAGE} ||= "SL::DB::Manager::$specs{MODEL}"->default_objects_per_page;
20 $specs{FORM_PARAMS} ||= [ qw(page per_page) ];
22 $specs{ONLY} = [ $specs{ONLY} ] if !ref $specs{ONLY};
23 $specs{ONLY_MAP} = @{ $specs{ONLY} } ? { map { ($_ => 1) } @{ $specs{ONLY} } } : { '__ALL__' => 1 };
25 $controller_paginate_spec{$class} = \%specs;
27 my %hook_params = @{ $specs{ONLY} } ? ( only => $specs{ONLY} ) : ();
28 $class->run_before('_save_current_paginate_params', %hook_params);
30 SL::Controller::Helper::GetModels::register_get_models_handlers(
32 callback => '_callback_handler_for_paginated',
33 get_models => '_get_models_handler_for_paginated',
37 # $::lxdebug->dump(0, "CONSPEC", \%specs);
40 sub get_paginate_spec {
41 my ($class_or_self) = @_;
43 return $controller_paginate_spec{ref($class_or_self) || $class_or_self};
46 sub get_current_paginate_params {
47 my ($self, %params) = @_;
49 my $spec = $self->get_paginate_spec;
51 my $priv = _priv($self);
52 $params{page} = $priv->{page} unless defined $params{page};
53 $params{per_page} = $priv->{per_page} unless defined $params{per_page};
55 my %paginate_params = (
56 page => ($params{page} * 1) || 1,
57 per_page => ($params{per_page} * 1) || $spec->{PER_PAGE},
60 my %paginate_args = ref($spec->{PAGINATE_ARGS}) eq 'CODE' ? %{ $spec->{PAGINATE_ARGS}->($self) }
61 : $spec->{PAGINATE_ARGS} ? do { my $sub = $spec->{PAGINATE_ARGS}; %{ $self->$sub() } }
63 my $calculated_params = "SL::DB::Manager::$spec->{MODEL}"->paginate(%paginate_params, args => \%paginate_args);
65 # $::lxdebug->dump(0, "get_current_paginate_params: ", $calculated_params);
67 return %{ $calculated_params };
70 sub disable_pagination {
72 _priv($self)->{disabled} = 1;
79 sub _save_current_paginate_params {
82 return if !_is_enabled($self);
84 my $paginate_spec = $self->get_paginate_spec;
86 page => $::form->{ $paginate_spec->{FORM_PARAMS}->[0] } || 1,
87 per_page => $::form->{ $paginate_spec->{FORM_PARAMS}->[1] } * 1,
90 # $::lxdebug->message(0, "saving current paginate params to " . $self->{PRIV()}->{page} . ' / ' . $self->{PRIV()}->{per_page});
93 sub _callback_handler_for_paginated {
94 my ($self, %params) = @_;
95 my $priv = _priv($self);
97 if (_is_enabled($self) && $priv->{page}) {
98 my $paginate_spec = $self->get_paginate_spec;
99 $params{ $paginate_spec->{FORM_PARAMS}->[0] } = $priv->{page};
100 $params{ $paginate_spec->{FORM_PARAMS}->[1] } = $priv->{per_page} if $priv->{per_page};
103 # $::lxdebug->dump(0, "CB handler for paginated; params nach modif:", \%params);
108 sub _get_models_handler_for_paginated {
109 my ($self, %params) = @_;
110 my $spec = $self->get_paginate_spec;
111 $params{model} ||= $spec->{MODEL};
113 "SL::DB::Manager::$params{model}"->paginate($self->get_current_paginate_params, args => \%params) if _is_enabled($self);
115 # $::lxdebug->dump(0, "GM handler for paginated; params nach modif (is_enabled? " . _is_enabled($self) . ")", \%params);
122 $self->{PRIV()} ||= {};
123 return $self->{PRIV()};
128 return !_priv($self)->{disabled} && ($self->get_paginate_spec->{ONLY_MAP}->{$self->action_name} || $self->get_paginate_spec->{ONLY_MAP}->{'__ALL__'});
140 SL::Controller::Helper::Paginated - A helper for semi-automatic handling
141 of paginating lists of database models in a controller
147 use SL::Controller::Helper::GetModels;
148 use SL::Controller::Helper::Paginated;
150 __PACKAGE__->make_paginated(
151 MODEL => 'BackgroundJobHistory',
152 ONLY => [ qw(list) ],
153 FORM_PARAMS => [ qw(page per_page) ],
159 my $paginated_models = $self->get_models;
160 $self->render('controller/list', ENTRIES => $paginated_models);
175 [% FOREACH entry = ENTRIES %]
183 [% L.paginate_controls %]
187 This specialized helper module enables controllers to display a
188 paginatable list of database models with as few lines as possible. It
189 can also be combined trivially with the L<SL::Controller::Sorted>
190 helper for sortable lists.
192 For this to work the controller has to provide the information which
193 indexes are eligible for paginateing etc. by a call to
194 L<make_paginated> at compile time.
196 The underlying functionality that enables the use of more than just
197 the paginate helper is provided by the controller helper
198 C<GetModels>. See the documentation for L<SL::Controller::Sorted> for
199 more information on it.
201 A template can use the method C<paginate_controls> from the layout
202 helper module C<L> which renders the links for navigation between the
205 This module requires that the Rose model managers use their C<Paginated>
208 The C<Paginated> helper hooks into the controller call to the action via
209 a C<run_before> hook. This is done so that it can remember the paginate
210 parameters that were used in the current view.
212 =head1 PACKAGE FUNCTIONS
216 =item C<make_paginated %paginate_spec>
218 This function must be called by a controller at compile time. It is
219 uesd to set the various parameters required for this helper to do its
222 The hash C<%paginate_spec> can include the following parameters:
228 Optional. A string: the name of the Rose database model that is used
229 as a default in certain cases. If this parameter is missing then it is
230 derived from the controller's package (e.g. for the controller
231 C<SL::Controller::BackgroundJobHistory> the C<MODEL> would default to
232 C<BackgroundJobHistory>).
234 =item * C<PAGINATE_ARGS>
236 Optional. Either a code reference or the name of function to be called
237 on the controller importing this helper.
239 If this funciton is given then the paginate helper calls it whenever
240 it has to count the total number of models for calculating the number
241 of pages to display. The function must return a hash reference with
242 elements suitable for passing to a Rose model manager's C<get_all>
245 This can be used e.g. when filtering is used.
249 Optional. An integer: the number of models to return per page.
251 Defaults to the underlying database model's default number of models
254 =item * C<FORM_PARAMS>
256 Optional. An array reference with exactly two strings that name the
257 indexes in C<$::form> in which the current page's number (the first
258 element in the array) and the number of models per page (the second
259 element in the array) are stored.
261 Defaults to the values C<page> and C<per_page> if missing.
265 Optional. An array reference containing a list of action names for
266 which the paginate parameters should be saved. If missing or empty then
267 all actions invoked on the controller are monitored.
273 =head1 INSTANCE FUNCTIONS
275 These functions are called on a controller instance.
279 =item C<get_paginate_spec>
281 Returns a hash containing the currently active paginate
282 parameters. The following keys are returned:
288 The currently active page number (numbering starts at 1).
292 Number of models per page (at least 1).
296 Number of pages to display (at least 1).
298 =item * C<common_pages>
300 An array reference with one hash reference for each possible
301 page. Each hash ref contains the keys C<active> (C<1> if that page is
302 the currently active page), C<page> (the page number this hash
303 reference describes) and C<visible> (whether or not it should be
308 =item C<get_current_paginate_params>
310 Returns a hash reference to the paginate spec structure given in the call
311 to L<make_paginated> after normalization (hash reference construction,
312 applying default parameters etc).
314 =item C<disable_pagination>
316 Disable pagination for the duration of the current action. Can be used
317 when using the attribute C<ONLY> to L<make_paginated> does not
328 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>