1 package SL::Controller::Helper::GetModels::Sorted;
4 use parent 'SL::Controller::Helper::GetModels::Base';
7 use List::MoreUtils qw(uniq);
9 use Rose::Object::MakeMethods::Generic (
10 scalar => [ qw(by dir specs form_data) ],
11 'scalar --get_set_init' => [ qw(form_params) ],
15 my ($self, %specs) = @_;
17 $self->set_get_models(delete $specs{get_models});
18 my %model_sort_spec = $self->get_models->manager->_sort_spec;
20 if (my $default = delete $specs{_default}) {
21 $self->by ($default->{by});
22 $self->dir($default->{dir});
24 $self->by ($model_sort_spec{default}[0]);
25 $self->dir($model_sort_spec{default}[1]);
28 while (my ($column, $spec) = each %specs) {
29 next if $column =~ m/^[A-Z_]+$/;
31 $spec = $specs{$column} = { title => $spec } if (ref($spec) || '') ne 'HASH';
33 $spec->{model} ||= $self->get_models->model;
34 $spec->{model_column} ||= $column;
36 $self->specs(\%specs);
38 $self->get_models->register_handlers(
39 callback => sub { shift; $self->_callback_handler_for_sorted(@_) },
40 get_models => sub { shift; $self->_get_models_handler_for_sorted(@_) },
43 # $::lxdebug->dump(0, "CONSPEC", \%specs);
47 my ($self, %params) = @_;
49 return %{ $self->form_data } if $self->form_data;
52 my ($by, $dir) = @{ $self->form_params };
53 my $source = $self->get_models->source;
55 if ($source->{ $by }) {
57 sort_by => $source->{$by},
58 sort_dir => defined($source->{$dir}) ? $source->{$dir} * 1 : undef,
60 } elsif (!$self->by) {
61 %sort_params = %params;
65 sort_dir => $self->dir,
69 $self->form_data(\%sort_params);
75 my ($self, %params) = @_;
77 my %sort_params = $self->read_params;
78 my $sort_spec = $self->specs->{ $sort_params{sort_by} };
80 $params{sort_by} = "SL::DB::Manager::$sort_spec->{model}"->make_sort_string(sort_by => $sort_spec->{model_column}, sort_dir => $sort_params{sort_dir});
85 sub set_report_generator_sort_options {
86 my ($self, %params) = @_;
88 $params{$_} or croak("Missing parameter '$_'") for qw(report sortable_columns);
90 my %current_sort_params = $self->read_params;
92 foreach my $col (@{ $params{sortable_columns} }) {
93 $params{report}->{columns}->{$col}->{link} = $self->get_models->get_callback(
95 sort_dir => ($current_sort_params{sort_by} eq $col ? 1 - $current_sort_params{sort_dir} : $current_sort_params{sort_dir}),
99 $params{report}->set_sort_indicator($current_sort_params{sort_by}, 1 - $current_sort_params{sort_dir});
101 if ($params{report}->{export}) {
102 $params{report}->{export}->{variable_list} = [ uniq(
103 @{ $params{report}->{export}->{variable_list} },
104 @{ $self->form_params }
113 sub _callback_handler_for_sorted {
114 my ($self, %params) = @_;
115 my %spec = $self->read_params;
117 if ($spec{sort_by}) {
118 $params{ $self->form_params->[0] } = $spec{sort_by};
119 $params{ $self->form_params->[1] } = $spec{sort_dir};
122 # $::lxdebug->dump(0, "CB handler for sorted; params nach modif:", \%params);
127 #sub _get_models_handler_for_sorted {
128 # my ($self, %params) = @_;
132 # # $::lxdebug->dump(0, "GM handler for sorted; params nach modif:", \%params);
138 sub init_form_params {
139 [ qw(sort_by sort_dir) ]
151 SL::Controller::Helper::Sorted - A helper for semi-automatic handling
152 of sorting lists of database models in a controller
158 use SL::Controller::Helper::GetModels;
159 use SL::Controller::Helper::Sorted;
161 __PACKAGE__->make_sorted(
162 DEFAULT_BY => 'run_at',
164 MODEL => 'BackgroundJobHistory',
165 ONLY => [ qw(list) ],
167 error => $::locale->text('Error'),
168 package_name => $::locale->text('Package name'),
169 run_at => $::locale->text('Run at'),
175 my $sorted_models = $self->get_models;
176 $self->render('controller/list', ENTRIES => $sorted_models);
185 <th>[% L.sortable_table_header('package_name') %]</th>
186 <th>[% L.sortable_table_header('run_at') %]</th>
187 <th>[% L.sortable_table_header('error') %]</th>
190 [% FOREACH entry = ENTRIES %]
192 <td>[% HTML.escape(entry.package_name) %]</td>
193 <td>[% HTML.escape(entry.run_at) %]</td>
194 <td>[% HTML.escape(entry.error) %]</td>
201 This specialized helper module enables controllers to display a
202 sortable list of database models with as few lines as possible.
204 For this to work the controller has to provide the information which
205 indexes are eligible for sorting etc. by a call to L<make_sorted> at
208 The underlying functionality that enables the use of more than just
209 the sort helper is provided by the controller helper C<GetModels>. It
210 provides mechanisms for helpers like this one to hook into certain
211 calls made by the controller (C<get_callback> and C<get_models>) so
212 that the specialized helpers can inject their parameters into the
213 calls to e.g. C<SL::DB::Manager::SomeModel::get_all>.
215 A template on the other hand can use the method
216 C<sortable_table_header> from the layout helper module C<L>.
218 This module requires that the Rose model managers use their C<Sorted>
221 The C<Sorted> helper hooks into the controller call to the action via
222 a C<run_before> hook. This is done so that it can remember the sort
223 parameters that were used in the current view.
225 =head1 PACKAGE FUNCTIONS
229 =item C<make_sorted %sort_spec>
231 This function must be called by a controller at compile time. It is
232 uesd to set the various parameters required for this helper to do its
235 There are two sorts of keys in the hash C<%sort_spec>. The first kind
236 is written in all upper-case. Those parameters are control
237 parameters. The second kind are all lower-case and represent indexes
238 that can be used for sorting (similar to database column names). The
239 second kind are also the indexes you use in a template when calling
240 C<[% L.sorted_table_header(...) %]>.
242 Control parameters include the following:
248 Optional. A string: the name of the Rose database model that is used
249 as a default in certain cases. If this parameter is missing then it is
250 derived from the controller's package (e.g. for the controller
251 C<SL::Controller::BackgroundJobHistory> the C<MODEL> would default to
252 C<BackgroundJobHistory>).
254 =item * C<DEFAULT_BY>
256 Optional. A string: the index to sort by if the user hasn't clicked on
257 any column yet (meaning: if the C<$::form> parameters for sorting do
258 not contain a valid index).
260 Defaults to the underlying database model's default sort column name.
262 =item * C<DEFAULT_DIR>
264 Optional. Default sort direction (ascending for trueish values,
265 descrending for falsish values).
267 Defaults to the underlying database model's default sort direction.
269 =item * C<FORM_PARAMS>
271 Optional. An array reference with exactly two strings that name the
272 indexes in C<$::form> in which the sort index (the first element in
273 the array) and sort direction (the second element in the array) are
276 Defaults to the values C<sort_by> and C<sort_dir> if missing.
280 Optional. An array reference containing a list of action names for
281 which the sort parameters should be saved. If missing or empty then
282 all actions invoked on the controller are monitored.
286 All keys that are written in all lower-case name indexes that can be
287 used for sorting. Each value to such a key can be either a string or a
288 hash reference containing certain elements. If the value is only a
289 string then such a hash reference is constructed, and the string is
290 used as the value for the C<title> key.
292 These possible elements are:
298 Required. A user-displayable title to be used by functions like the
299 layout helper's C<sortable_table_header>. Does not have a default
302 Note that this string must be the untranslated English version of the
303 string. The titles will be translated whenever they're requested.
307 Optional. The name of a Rose database model this sort index refers
308 to. If missing then the value of C<$sort_spec{MODEL}> is used.
310 =item * C<model_column>
312 Optional. The name of the Rose database model column this sort index
313 refers to. It must be one of the columns named by the model's
314 C<Sorted> helper (not to be confused with the controller's C<Sorted>
317 If missing it defaults to the key in C<%sort_spec> for which this hash
318 reference is the value.
324 =head1 INSTANCE FUNCTIONS
326 These functions are called on a controller instance.
330 =item C<get_sort_spec>
332 Returns a hash containing the currently active sort parameters.
334 The key C<by> contains the active sort index referring to the
335 C<%sort_spec> given to L<make_sorted>.
337 The key C<dir> is either C<1> or C<0>.
339 =item C<get_current_sort_params>
341 Returns a hash reference to the sort spec structure given in the call
342 to L<make_sorted> after normalization (hash reference construction,
343 applying default parameters etc).
345 =item C<set_report_generator_sort_options %params>
347 This function does three things with an instance of
348 L<SL::ReportGenerator>:
352 =item 1. it sets the sort indicator,
354 =item 2. it sets the the links for those column headers that are
357 =item 3. it adds the C<FORM_PARAMS> fields to the list of variables in
358 the report generator's export options.
362 The report generator instance must be passed as the parameter
363 C<report>. The parameter C<sortable_columns> must be an array
364 reference of column names that are sortable.
366 The report generator instance must already have its columns and export
367 options set via calls to its L<SL::ReportGenerator::set_columns> and
368 L<SL::ReportGenerator::set_export_options> functions.
378 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>