Upgrade-Doku: Hinweis auf benötigtes Perl-Modul IPC::Run
[kivitendo-erp.git] / SL / DB / Helper / Sorted.pm
1 package SL::DB::Helper::Sorted;
2
3 use strict;
4
5 require Exporter;
6 our @ISA    = qw(Exporter);
7 our @EXPORT = qw(get_all_sorted make_sort_string);
8
9 my %sort_spec;
10
11 sub make_sort_string {
12   my ($class, %params) = @_;
13
14   my $sort_spec        = _get_sort_spec($class);
15
16   my $sort_dir         = defined($params{sort_dir}) ? $params{sort_dir} * 1 : $sort_spec->{default}->[1];
17   my $sort_dir_str     = $sort_dir ? 'ASC' : 'DESC';
18
19   my $sort_by          = $params{sort_by} || { };
20   $sort_by             = $sort_spec->{default}->[0] unless $sort_spec->{columns}->{$sort_by};
21
22   my $nulls_str        = '';
23   if ($sort_spec->{nulls}) {
24     $nulls_str = ref($sort_spec->{nulls}) ? ($sort_spec->{nulls}->{$sort_by} || $sort_spec->{nulls}->{default}) : $sort_spec->{nulls};
25     $nulls_str = " NULLS ${nulls_str}" if $nulls_str;
26   }
27
28   my $sort_by_str = $sort_spec->{columns}->{$sort_by};
29   $sort_by_str    = [ $sort_by_str ] unless ref($sort_by_str) eq 'ARRAY';
30
31   # generate tiebreaker
32   push @$sort_by_str, @{ $sort_spec->{tiebreaker} };
33
34   $sort_by_str    = join(', ', map { "${_} ${sort_dir_str}${nulls_str}" } @{ $sort_by_str });
35
36   return wantarray ? ($sort_by, $sort_dir, $sort_by_str) : $sort_by_str;
37 }
38
39 sub get_all_sorted {
40   my ($class, %params) = @_;
41   my $sort_str         = $class->make_sort_string(sort_by => delete($params{sort_by}), sort_dir => delete($params{sort_dir}));
42
43   return $class->get_all(sort_by => $sort_str, %params);
44 }
45
46 sub _get_sort_spec {
47   my ($class) = @_;
48   return $sort_spec{$class} ||= _make_sort_spec($class);
49 }
50
51 sub _make_sort_spec {
52   my ($class) = @_;
53
54   my %sort_spec = defined &{ "${class}::_sort_spec" } ? $class->_sort_spec : ();
55
56   my $meta = $class->object_class->meta;
57   my $table = $meta->table;
58
59   if (!$sort_spec{default}) {
60     my @primary_keys = $meta->primary_key;
61     $sort_spec{default} = [ "" . $primary_keys[0], 1 ];
62   }
63
64   $sort_spec{columns} ||= { SIMPLE => [ map { "$_" } $meta->columns ] };
65
66   if ($sort_spec{columns}->{SIMPLE}) {
67     if (!ref($sort_spec{columns}->{SIMPLE}) && ($sort_spec{columns}->{SIMPLE} eq 'ALL')) {
68       map { $sort_spec{columns}->{"$_"} ||= "${table}.${_}"} @{ $meta->columns };
69       delete $sort_spec{columns}->{SIMPLE};
70     } else {
71       map { $sort_spec{columns}->{$_} = "${table}.${_}" } @{ delete($sort_spec{columns}->{SIMPLE}) };
72     }
73   }
74
75   $sort_spec{tiebreaker} ||= [ map { "${table}.${_}" } $meta->primary_key ];
76
77   return \%sort_spec;
78 }
79
80 1;
81
82 __END__
83
84 =encoding utf8
85
86 =head1 NAME
87
88 SL::DB::Helper::Sorted - Mixin for a manager class that handles
89 sorting of database records
90
91 =head1 SYNOPSIS
92
93   package SL::DB::Manager::Message;
94
95   use SL::DB::Helper::Sorted;
96
97   sub _sort_spec {
98     return ( columns => { recipient_id => [ 'CASE
99                                              WHEN recipient_group_id IS NULL THEN lower(recipient.name)
100                                              ELSE                                 lower(recipient_group.name)
101                                              END',                                      ],
102                           sender_id    => [ 'lower(sender.name)',                       ],
103                           created_at   => [ 'created_at',                               ],
104                           subject      => [ 'lower(subject)',                           ],
105                           status       => [ 'NOT COALESCE(unread, FALSE)', 'created_at' ],
106                         },
107              default => [ 'status', 1 ],
108              nulls   => { default => 'LAST',
109                           subject => 'FIRST',
110                         }
111            );
112   }
113
114   package SL::Controller::Message;
115
116   sub action_list {
117     my $messages = SL::DB::Manager::Message->get_all_sorted(sort_by  => $::form->{sort_by},
118                                                             sort_dir => $::form->{sort_dir});
119   }
120
121 =head1 CLASS FUNCTIONS
122
123 =over 4
124
125 =item C<make_sort_string %params>
126
127 Evaluates C<$params{sort_by}> and C<$params{sort_dir}> and returns an
128 SQL string suitable for sorting. The package this package is mixed
129 into has to provide a method L</_sort_spec> that returns a hash whose
130 structure is explained below. That hash is authoritative in which
131 columns may be sorted, which column to sort by by default and how to
132 handle C<NULL> values.
133
134 Returns the SQL string in scalar context. In array context it returns
135 three values: the actual column it sorts by (suitable for another call
136 to L</make_sort_string>), the actual sort direction (either 0 or 1)
137 and the SQL string.
138
139 =item C<get_all_sorted %params>
140
141 Returns C<< $class->get_all >> with C<sort_by> set to the value
142 returned by c<< $class->make_sort_string(%params) >>.
143
144 =back
145
146 =head1 CLASS FUNCTIONS PROVIDED BY THE MIXING PACKAGE
147
148 =over 4
149
150 =item C<_sort_spec>
151
152 This method is actually not part of this package but can be provided
153 by the package this helper is mixed into. If it isn't then all columns
154 of the corresponding table (as returned by the model's meta data) will
155 be eligible for sorting.
156
157 Returns a hash with the following keys:
158
159 =over 2
160
161 =item C<default>
162
163 A two-element array containing the name and direction by which to sort
164 in default cases. Example:
165
166   default => [ 'name', 1 ],
167
168 Defaults to the table's primary key column (the first column if the
169 primary key is composited).
170
171 =item C<columns>
172
173 A hash reference. Its keys are column names, and its values are SQL
174 strings by which to sort. Example:
175
176   columns => { SIMPLE                  => [ 'transaction_description', 'orddate' ],
177                the_date                => 'CASE WHEN oe.quotation THEN oe.quodate ELSE oe.orddate END',
178                customer_name           => 'lower(customer.name)',
179              },
180
181 If sorting is requested for a column that is not a key in this hash
182 then the default column name will be used.
183
184 The value can be either a scalar or an array reference. If it's the
185 latter then both the sort direction as well as the null handling will
186 be appended to each of its members.
187
188 The special key C<SIMPLE> can be a scalar or an array reference. If it
189 is an array reference then it contains column names that are mapped
190 1:1 onto the table's columns. If it is the scalar 'ALL' then all
191 columns in that model's meta data are mapped 1:1 unless the C<columns>
192 hash already contains a key for that column.
193
194 If C<columns> is missing then all columns of the model will be
195 eligible for sorting. The list of columns is looked up in the model's
196 meta data.
197
198 =item C<nulls>
199
200 Either a scalar or a hash reference determining where C<NULL> values
201 will be sorted. If undefined then the decision is left to the
202 database.
203
204 If it is a scalar then the same value will be used for all
205 classes. The value is either C<FIRST> or C<LAST>.
206
207 If it is a hash reference then its keys are column names (not SQL
208 names). The values are either C<FIRST> or C<LAST>. If a column name is
209 not found in this hash then the special key C<default> will be looked
210 up and used if it is found.
211
212 Example:
213
214   nulls => { transaction_description => 'FIRST',
215              customer_name           => 'FIRST',
216              default                 => 'LAST',
217            },
218
219 =item C<tiebreaker>
220
221 Optional tiebreaker sorting that gets appended to any user requested sorting.
222 Needed to make sorting by non unique columns deterministic.
223
224 If present must be an arrayref of column sort specs (see C<column>).
225
226 Defaults to primary keys.
227
228 =back
229
230 =back
231
232 =head1 BUGS
233
234 Nothing here yet.
235
236 =head1 AUTHOR
237
238 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
239
240 =cut