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) ];
21 $specs{PAGINATE_ARGS} ||= '__FILTER__';
23 $specs{ONLY} = [ $specs{ONLY} ] if !ref $specs{ONLY};
24 $specs{ONLY_MAP} = @{ $specs{ONLY} } ? { map { ($_ => 1) } @{ $specs{ONLY} } } : { '__ALL__' => 1 };
26 $controller_paginate_spec{$class} = \%specs;
28 my %hook_params = @{ $specs{ONLY} } ? ( only => $specs{ONLY} ) : ();
29 $class->run_before('_save_current_paginate_params', %hook_params);
31 SL::Controller::Helper::GetModels::register_get_models_handlers(
33 callback => '_callback_handler_for_paginated',
34 get_models => '_get_models_handler_for_paginated',
38 # $::lxdebug->dump(0, "CONSPEC", \%specs);
41 sub get_paginate_spec {
42 my ($class_or_self) = @_;
44 return $controller_paginate_spec{ref($class_or_self) || $class_or_self};
47 sub get_current_paginate_params {
48 my ($self, %params) = @_;
50 my $spec = $self->get_paginate_spec;
52 my $priv = _priv($self);
53 $params{page} = $priv->{page} unless defined $params{page};
54 $params{per_page} = $priv->{per_page} unless defined $params{per_page};
56 my %paginate_params = (
57 page => ($params{page} * 1) || 1,
58 per_page => ($params{per_page} * 1) || $spec->{PER_PAGE},
61 my %paginate_args = ref($spec->{PAGINATE_ARGS}) eq 'CODE' ? %{ $spec->{PAGINATE_ARGS}->($self) }
62 : $spec->{PAGINATE_ARGS} eq '__FILTER__' ? $self->get_current_filter_params
63 : $spec->{PAGINATE_ARGS} ? do { my $sub = $spec->{PAGINATE_ARGS}; %{ $self->$sub() } }
65 my $calculated_params = "SL::DB::Manager::$spec->{MODEL}"->paginate(%paginate_params, args => \%paginate_args);
67 # $::lxdebug->dump(0, "get_current_paginate_params: ", $calculated_params);
69 return %{ $calculated_params };
72 sub disable_pagination {
74 _priv($self)->{disabled} = 1;
81 sub _save_current_paginate_params {
84 return if !_is_enabled($self);
86 my $paginate_spec = $self->get_paginate_spec;
88 page => $::form->{ $paginate_spec->{FORM_PARAMS}->[0] } || 1,
89 per_page => $::form->{ $paginate_spec->{FORM_PARAMS}->[1] } * 1,
92 # $::lxdebug->message(0, "saving current paginate params to " . $self->{PRIV()}->{page} . ' / ' . $self->{PRIV()}->{per_page});
95 sub _callback_handler_for_paginated {
96 my ($self, %params) = @_;
97 my $priv = _priv($self);
99 if (_is_enabled($self) && $priv->{page}) {
100 my $paginate_spec = $self->get_paginate_spec;
101 $params{ $paginate_spec->{FORM_PARAMS}->[0] } = $priv->{page};
102 $params{ $paginate_spec->{FORM_PARAMS}->[1] } = $priv->{per_page} if $priv->{per_page};
105 # $::lxdebug->dump(0, "CB handler for paginated; params nach modif:", \%params);
110 sub _get_models_handler_for_paginated {
111 my ($self, %params) = @_;
112 my $spec = $self->get_paginate_spec;
113 $params{model} ||= $spec->{MODEL};
115 "SL::DB::Manager::$params{model}"->paginate($self->get_current_paginate_params, args => \%params) if _is_enabled($self);
117 # $::lxdebug->dump(0, "GM handler for paginated; params nach modif (is_enabled? " . _is_enabled($self) . ")", \%params);
124 $self->{PRIV()} ||= {};
125 return $self->{PRIV()};
130 return !_priv($self)->{disabled} && ($self->get_paginate_spec->{ONLY_MAP}->{$self->action_name} || $self->get_paginate_spec->{ONLY_MAP}->{'__ALL__'});
142 SL::Controller::Helper::Paginated - A helper for semi-automatic handling
143 of paginating lists of database models in a controller
149 use SL::Controller::Helper::GetModels;
150 use SL::Controller::Helper::Paginated;
152 __PACKAGE__->make_paginated(
153 MODEL => 'BackgroundJobHistory',
154 ONLY => [ qw(list) ],
155 FORM_PARAMS => [ qw(page per_page) ],
161 my $paginated_models = $self->get_models;
162 $self->render('controller/list', ENTRIES => $paginated_models);
177 [% FOREACH entry = ENTRIES %]
185 [% L.paginate_controls %]
189 This specialized helper module enables controllers to display a
190 paginatable list of database models with as few lines as possible. It
191 can also be combined trivially with the L<SL::Controller::Sorted>
192 helper for sortable lists.
194 For this to work the controller has to provide the information which
195 indexes are eligible for paginateing etc. by a call to
196 L<make_paginated> at compile time.
198 The underlying functionality that enables the use of more than just
199 the paginate helper is provided by the controller helper
200 C<GetModels>. See the documentation for L<SL::Controller::Sorted> for
201 more information on it.
203 A template can use the method C<paginate_controls> from the layout
204 helper module C<L> which renders the links for navigation between the
207 This module requires that the Rose model managers use their C<Paginated>
210 The C<Paginated> helper hooks into the controller call to the action via
211 a C<run_before> hook. This is done so that it can remember the paginate
212 parameters that were used in the current view.
214 =head1 PACKAGE FUNCTIONS
218 =item C<make_paginated %paginate_spec>
220 This function must be called by a controller at compile time. It is
221 uesd to set the various parameters required for this helper to do its
224 The hash C<%paginate_spec> can include the following parameters:
230 Optional. A string: the name of the Rose database model that is used
231 as a default in certain cases. If this parameter is missing then it is
232 derived from the controller's package (e.g. for the controller
233 C<SL::Controller::BackgroundJobHistory> the C<MODEL> would default to
234 C<BackgroundJobHistory>).
236 =item * C<PAGINATE_ARGS>
238 Optional. Either a code reference or the name of function to be called
239 on the controller importing this helper.
241 If this funciton is given then the paginate helper calls it whenever
242 it has to count the total number of models for calculating the number
243 of pages to display. The function must return a hash reference with
244 elements suitable for passing to a Rose model manager's C<get_all>
247 This can be used e.g. when filtering is used.
251 Optional. An integer: the number of models to return per page.
253 Defaults to the underlying database model's default number of models
256 =item * C<FORM_PARAMS>
258 Optional. An array reference with exactly two strings that name the
259 indexes in C<$::form> in which the current page's number (the first
260 element in the array) and the number of models per page (the second
261 element in the array) are stored.
263 Defaults to the values C<page> and C<per_page> if missing.
267 Optional. An array reference containing a list of action names for
268 which the paginate parameters should be saved. If missing or empty then
269 all actions invoked on the controller are monitored.
275 =head1 INSTANCE FUNCTIONS
277 These functions are called on a controller instance.
281 =item C<get_paginate_spec>
283 Returns a hash containing the currently active paginate
284 parameters. The following keys are returned:
290 The currently active page number (numbering starts at 1).
294 Number of models per page (at least 1).
298 Number of pages to display (at least 1).
300 =item * C<common_pages>
302 An array reference with one hash reference for each possible
303 page. Each hash ref contains the keys C<active> (C<1> if that page is
304 the currently active page), C<page> (the page number this hash
305 reference describes) and C<visible> (whether or not it should be
310 =item C<get_current_paginate_params>
312 Returns a hash reference to the paginate spec structure given in the call
313 to L<make_paginated> after normalization (hash reference construction,
314 applying default parameters etc).
316 =item C<disable_pagination>
318 Disable pagination for the duration of the current action. Can be used
319 when using the attribute C<ONLY> to L<make_paginated> does not
330 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>