1 package SL::Controller::Helper::GetModels::Paginated;
4 use parent 'SL::Controller::Helper::GetModels::Base';
6 use List::Util qw(min);
8 use Rose::Object::MakeMethods::Generic (
9 scalar => [ qw(disabled per_page) ],
10 'scalar --get_set_init' => [ qw(form_params paginate_args) ],
14 my ($self, %specs) = @_;
16 $self->set_get_models(delete $specs{get_models});
17 $self->SUPER::init(%specs);
19 $self->per_page($self->get_models->manager->default_objects_per_page) unless $self->per_page;
21 $self->get_models->register_handlers(
22 callback => sub { shift; $self->_callback_handler_for_paginated(@_) },
23 get_models => sub { shift; $self->_get_models_handler_for_paginated(@_) },
26 # $::lxdebug->dump(0, "CONSPEC", \%specs);
29 sub get_current_paginate_params {
30 my ($self, %args) = @_;
31 return () unless $self->is_enabled;
33 my %paginate_params = $self->final_params(%args);
35 # try to use Filtered if available and nothing else is configured, but don't
36 # blow up if the controller does not use Filtered
37 my %paginate_args = ref($self->paginate_args) eq 'CODE' ? %{ $self->paginate_args->($self) }
38 : $self->paginate_args eq '__FILTER__'
39 && $self->get_models->filtered ? %{ $self->get_models->filtered->get_current_filter_params }
40 : $self->paginate_args ne '__FILTER__' ? do { my $sub = $self->paginate_args; %{ $self->get_models->controller->$sub() } }
43 %args = $self->merge_args(\%args, \%paginate_args);
45 my $calculated_params = $self->get_models->manager->paginate(%paginate_params, args => \%args);
47 # $::lxdebug->dump(0, "get_current_paginate_params: ", $calculated_params);
49 return %{ $calculated_params };
52 sub disable_pagination {
58 my ($self, %params) = @_;
61 page => $::form->{ $self->form_params->[0] } || 1,
62 per_page => $::form->{ $self->form_params->[1] } * 1,
65 # my $priv = _priv($self);
66 $params{page} = $from_form->{page} unless defined $params{page};
67 $params{per_page} = $from_form->{per_page} unless defined $params{per_page};
69 $params{page} = ($params{page} * 1) || 1;
70 $params{per_page} = ($params{per_page} * 1) || $self->per_page;
79 sub init_form_params {
83 sub init_paginate_args {
87 sub _callback_handler_for_paginated {
88 my ($self, %params) = @_;
89 my %form_params = $self->final_params;
90 # my $priv = _priv($self);
92 if ($self->is_enabled && $form_params{page}) {
93 $params{ $self->form_params->[0] } = $form_params{page};
94 $params{ $self->form_params->[1] } = $form_params{per_page} if $form_params{per_page};
97 # $::lxdebug->dump(0, "CB handler for paginated; params nach modif:", \%params);
102 sub _get_models_handler_for_paginated {
103 my ($self, %params) = @_;
105 $self->get_models->manager->paginate($self->final_params, args => \%params) if $self->is_enabled;
107 # $::lxdebug->dump(0, "GM handler for paginated; params nach modif (is_enabled? " . _is_enabled($self) . ")", \%params);
114 return !$self->disabled;
126 SL::Controller::Helper::Paginated - A helper for semi-automatic handling
127 of paginating lists of database models in a controller
133 use SL::Controller::Helper::GetModels;
134 use SL::Controller::Helper::Paginated;
136 __PACKAGE__->make_paginated(
137 MODEL => 'BackgroundJobHistory',
138 ONLY => [ qw(list) ],
139 FORM_PARAMS => [ qw(page per_page) ],
145 my $paginated_models = $self->get_models;
146 $self->render('controller/list', ENTRIES => $paginated_models);
161 [% FOREACH entry = ENTRIES %]
169 [% L.paginate_controls %]
173 This specialized helper module enables controllers to display a
174 paginatable list of database models with as few lines as possible. It
175 can also be combined trivially with the L<SL::Controller::Sorted>
176 helper for sortable lists.
178 For this to work the controller has to provide the information which
179 indexes are eligible for paginateing etc. by a call to
180 L<make_paginated> at compile time.
182 The underlying functionality that enables the use of more than just
183 the paginate helper is provided by the controller helper
184 C<GetModels>. See the documentation for L<SL::Controller::Sorted> for
185 more information on it.
187 A template can use the method C<paginate_controls> from the layout
188 helper module C<L> which renders the links for navigation between the
191 This module requires that the Rose model managers use their C<Paginated>
194 The C<Paginated> helper hooks into the controller call to the action via
195 a C<run_before> hook. This is done so that it can remember the paginate
196 parameters that were used in the current view.
198 =head1 PACKAGE FUNCTIONS
202 =item C<make_paginated %paginate_spec>
204 This function must be called by a controller at compile time. It is
205 uesd to set the various parameters required for this helper to do its
208 The hash C<%paginate_spec> can include the following parameters:
214 Optional. A string: the name of the Rose database model that is used
215 as a default in certain cases. If this parameter is missing then it is
216 derived from the controller's package (e.g. for the controller
217 C<SL::Controller::BackgroundJobHistory> the C<MODEL> would default to
218 C<BackgroundJobHistory>).
220 =item * C<PAGINATE_ARGS>
222 Optional. Either a code reference or the name of function to be called
223 on the controller importing this helper.
225 If this funciton is given then the paginate helper calls it whenever
226 it has to count the total number of models for calculating the number
227 of pages to display. The function must return a hash reference with
228 elements suitable for passing to a Rose model manager's C<get_all>
231 This can be used e.g. when filtering is used.
235 Optional. An integer: the number of models to return per page.
237 Defaults to the underlying database model's default number of models
240 =item * C<FORM_PARAMS>
242 Optional. An array reference with exactly two strings that name the
243 indexes in C<$::form> in which the current page's number (the first
244 element in the array) and the number of models per page (the second
245 element in the array) are stored.
247 Defaults to the values C<page> and C<per_page> if missing.
251 Optional. An array reference containing a list of action names for
252 which the paginate parameters should be saved. If missing or empty then
253 all actions invoked on the controller are monitored.
259 =head1 INSTANCE FUNCTIONS
261 These functions are called on a controller instance.
265 =item C<get_paginate_spec>
267 Returns a hash containing the currently active paginate
268 parameters. The following keys are returned:
274 The currently active page number (numbering starts at 1).
278 Number of models per page (at least 1).
282 Number of pages to display (at least 1).
284 =item * C<common_pages>
286 An array reference with one hash reference for each possible
287 page. Each hash ref contains the keys C<active> (C<1> if that page is
288 the currently active page), C<page> (the page number this hash
289 reference describes) and C<visible> (whether or not it should be
294 =item C<get_current_paginate_params>
296 Returns a hash reference to the paginate spec structure given in the call
297 to L<make_paginated> after normalization (hash reference construction,
298 applying default parameters etc).
300 =item C<disable_pagination>
302 Disable pagination for the duration of the current action. Can be used
303 when using the attribute C<ONLY> to L<make_paginated> does not
314 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>