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(per_page form_data paginated_args calculated_params) ],
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);
30 my ($self, %params) = @_;
32 return %{ $self->form_data } if $self->form_data;
33 my $source = $self->get_models->source;
36 page => $source->{ $self->form_params->[0] } || 1,
37 per_page => $source->{ $self->form_params->[1] } * 1,
40 # my $priv = _priv($self);
41 $params{page} = $from_form->{page} unless defined $params{page};
42 $params{per_page} = $from_form->{per_page} unless defined $params{per_page};
44 $params{page} = ($params{page} * 1) || 1;
45 $params{per_page} = ($params{per_page} * 1) || $self->per_page;
47 $self->form_data(\%params);
53 my ($self, %args) = @_;
54 # return () unless $self->is_enabled;
55 my %paginate_params = $self->read_params;
57 # try to use Filtered if available and nothing else is configured, but don't
58 # blow up if the controller does not use Filtered
59 my %paginate_args = ref($self->paginate_args) eq 'CODE' ? %{ $self->paginate_args->($self) }
60 : $self->paginate_args eq '__FILTER__'
61 && $self->get_models->filtered ? $self->get_models->filtered->read_params
62 : $self->paginate_args ne '__FILTER__' ? do { my $sub = $self->paginate_args; %{ $self->get_models->controller->$sub() } }
65 %args = $self->merge_args(\%args, \%paginate_args);
67 my $calculated_params = $self->get_models->manager->paginate(%paginate_params, args => \%args);
69 $self->paginated_args(\%args);
70 $self->calculated_params($calculated_params);
75 sub get_current_paginate_params {
76 my ($self, %args) = @_;
77 return () unless $self->is_enabled;
78 %{ $self->calculated_params };
85 sub _callback_handler_for_paginated {
86 my ($self, %params) = @_;
87 my %form_params = $self->read_params;
89 if ($self->is_enabled && $form_params{page}) {
90 $params{ $self->form_params->[0] } = $form_params{page};
91 $params{ $self->form_params->[1] } = $form_params{per_page} if $form_params{per_page};
94 # $::lxdebug->dump(0, "CB handler for paginated; params nach modif:", \%params);
99 sub _get_models_handler_for_paginated {
100 my ($self, %params) = @_;
102 $self->get_models->manager->paginate(%{ $self->calculated_params }, args => \%params) if $self->is_enabled;
104 # $::lxdebug->dump(0, "GM handler for paginated; params nach modif (is_enabled? " . _is_enabled($self) . ")", \%params);
108 sub init_form_params {
109 [ qw(page per_page) ]
112 sub init_paginate_args {
125 SL::Controller::Helper::Paginated - A helper for semi-automatic handling
126 of paginating lists of database models in a controller
132 use SL::Controller::Helper::GetModels;
133 use SL::Controller::Helper::Paginated;
135 __PACKAGE__->make_paginated(
136 MODEL => 'BackgroundJobHistory',
137 ONLY => [ qw(list) ],
138 FORM_PARAMS => [ qw(page per_page) ],
144 my $paginated_models = $self->get_models;
145 $self->render('controller/list', ENTRIES => $paginated_models);
160 [% FOREACH entry = ENTRIES %]
168 [% L.paginate_controls %]
172 This specialized helper module enables controllers to display a
173 paginatable list of database models with as few lines as possible. It
174 can also be combined trivially with the L<SL::Controller::Sorted>
175 helper for sortable lists.
177 For this to work the controller has to provide the information which
178 indexes are eligible for paginateing etc. by a call to
179 L<make_paginated> at compile time.
181 The underlying functionality that enables the use of more than just
182 the paginate helper is provided by the controller helper
183 C<GetModels>. See the documentation for L<SL::Controller::Sorted> for
184 more information on it.
186 A template can use the method C<paginate_controls> from the layout
187 helper module C<L> which renders the links for navigation between the
190 This module requires that the Rose model managers use their C<Paginated>
193 The C<Paginated> helper hooks into the controller call to the action via
194 a C<run_before> hook. This is done so that it can remember the paginate
195 parameters that were used in the current view.
197 =head1 PACKAGE FUNCTIONS
201 =item C<make_paginated %paginate_spec>
203 This function must be called by a controller at compile time. It is
204 uesd to set the various parameters required for this helper to do its
207 The hash C<%paginate_spec> can include the following parameters:
213 Optional. A string: the name of the Rose database model that is used
214 as a default in certain cases. If this parameter is missing then it is
215 derived from the controller's package (e.g. for the controller
216 C<SL::Controller::BackgroundJobHistory> the C<MODEL> would default to
217 C<BackgroundJobHistory>).
219 =item * C<PAGINATE_ARGS>
221 Optional. Either a code reference or the name of function to be called
222 on the controller importing this helper.
224 If this funciton is given then the paginate helper calls it whenever
225 it has to count the total number of models for calculating the number
226 of pages to display. The function must return a hash reference with
227 elements suitable for passing to a Rose model manager's C<get_all>
230 This can be used e.g. when filtering is used.
234 Optional. An integer: the number of models to return per page.
236 Defaults to the underlying database model's default number of models
239 =item * C<FORM_PARAMS>
241 Optional. An array reference with exactly two strings that name the
242 indexes in C<$::form> in which the current page's number (the first
243 element in the array) and the number of models per page (the second
244 element in the array) are stored.
246 Defaults to the values C<page> and C<per_page> if missing.
250 Optional. An array reference containing a list of action names for
251 which the paginate parameters should be saved. If missing or empty then
252 all actions invoked on the controller are monitored.
258 =head1 INSTANCE FUNCTIONS
260 These functions are called on a controller instance.
264 =item C<get_paginate_spec>
266 Returns a hash containing the currently active paginate
267 parameters. The following keys are returned:
273 The currently active page number (numbering starts at 1).
277 Number of models per page (at least 1).
281 Number of pages to display (at least 1).
283 =item * C<common_pages>
285 An array reference with one hash reference for each possible
286 page. Each hash ref contains the keys C<active> (C<1> if that page is
287 the currently active page), C<page> (the page number this hash
288 reference describes) and C<visible> (whether or not it should be
293 =item C<get_current_paginate_params>
295 Returns a hash reference to the paginate spec structure given in the call
296 to L<make_paginated> after normalization (hash reference construction,
297 applying default parameters etc).
299 =item C<disable_pagination>
301 Disable pagination for the duration of the current action. Can be used
302 when using the attribute C<ONLY> to L<make_paginated> does not
313 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>