bug 8215: (followup) make sure C4::CourseReserves doesn't export anything
[koha.git] / C4 / Utils / DataTables.pm
1 package C4::Utils::DataTables;
2
3 # Copyright 2011 BibLibre
4 #
5 # This file is part of Koha.
6 #
7 # Koha is free software; you can redistribute it and/or modify it under the
8 # terms of the GNU General Public License as published by the Free Software
9 # Foundation; either version 2 of the License, or (at your option) any later
10 # version.
11 #
12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
14 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
15 #
16 # You should have received a copy of the GNU General Public License along
17 # with Koha; if not, write to the Free Software Foundation, Inc.,
18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19
20 use Modern::Perl;
21 require Exporter;
22
23 use vars qw($VERSION @ISA @EXPORT);
24
25 BEGIN {
26     $VERSION    = 3.07.00.049,
27
28     @ISA        = qw(Exporter);
29     @EXPORT     = qw(dt_build_orderby dt_build_having dt_get_params dt_build_query);
30 }
31
32 =head1 NAME
33
34 C4::Utils::DataTables - Utility subs for building query when DataTables source is AJAX
35
36 =head1 SYNOPSYS
37
38     use CGI;
39     use C4::Context;
40     use C4::Utils::DataTables;
41
42     my $input = new CGI;
43     my $vars = $input->Vars;
44
45     my $query = qq{
46         SELECT surname, firstname
47         FROM borrowers
48         WHERE borrowernumber = ?
49     };
50     my ($having, $having_params) = dt_build_having($vars);
51     $query .= $having;
52     $query .= dt_build_orderby($vars);
53     $query .= " LIMIT ?,? ";
54
55     my $dbh = C4::Context->dbh;
56     my $sth = $dbh->prepare($query);
57     $sth->execute(
58         $vars->{'borrowernumber'},
59         @$having_params,
60         $vars->{'iDisplayStart'},
61         $vars->{'iDisplayLength'}
62     );
63     ...
64
65 =head1 DESCRIPTION
66
67     This module provide two utility functions to build a part of the SQL query,
68     depending on DataTables parameters.
69     One function build the 'ORDER BY' part, and the other the 'HAVING' part.
70
71 =head1 FUNCTIONS
72
73 =head2 dt_build_orderby
74
75     my $orderby = dt_build_orderby($dt_param);
76     This function takes a reference to a hash containing DataTables parameters
77     and build the corresponding 'ORDER BY' clause.
78     This hash must contains the following keys:
79         iSortCol_N, where N is a number from 0 to the number of columns to sort on minus 1
80         sSortDir_N is the sorting order ('asc' or 'desc) for the corresponding column
81         mDataProp_N is a mapping between the column index, and the name of a SQL field
82
83 =cut
84
85 sub dt_build_orderby {
86     my $param = shift;
87
88     my $i = 0;
89     my $orderby;
90     my @orderbys;
91     while(exists $param->{'iSortCol_'.$i}){
92         my $iSortCol = $param->{'iSortCol_'.$i};
93         my $sSortDir = $param->{'sSortDir_'.$i};
94         my $mDataProp = $param->{'mDataProp_'.$iSortCol};
95         my @sort_fields = $param->{$mDataProp.'_sorton'}
96             ? split(' ', $param->{$mDataProp.'_sorton'})
97             : ();
98         if(@sort_fields > 0) {
99             push @orderbys, "$_ $sSortDir" foreach (@sort_fields);
100         } else {
101             push @orderbys, "$mDataProp $sSortDir";
102         }
103         $i++;
104     }
105
106     $orderby = " ORDER BY " . join(',', @orderbys) . " " if @orderbys;
107     return $orderby;
108 }
109
110 =head2 dt_build_having
111
112     my ($having, $having_params) = dt_build_having($dt_params)
113
114     This function takes a reference to a hash containing DataTables parameters
115     and build the corresponding 'HAVING' clause.
116     This hash must contains the following keys:
117         sSearch is the text entered in the global filter
118         iColumns is the number of columns
119         bSearchable_N is a boolean value that is true if the column is searchable
120         mDataProp_N is a mapping between the column index, and the name of a SQL field
121         sSearch_N is the text entered in individual filter for column N
122
123 =cut
124
125 sub dt_build_having {
126     my $param = shift;
127
128     my @filters;
129     my @params;
130
131     # Global filter
132     if($param->{'sSearch'}) {
133         my $sSearch = $param->{'sSearch'};
134         my $i = 0;
135         my @gFilters;
136         my @gParams;
137         while($i < $param->{'iColumns'}) {
138             if($param->{'bSearchable_'.$i} eq 'true') {
139                 my $mDataProp = $param->{'mDataProp_'.$i};
140                 my @filter_fields = $param->{$mDataProp.'_filteron'}
141                     ? split(' ', $param->{$mDataProp.'_filteron'})
142                     : ();
143                 if(@filter_fields > 0) {
144                     foreach my $field (@filter_fields) {
145                         push @gFilters, " $field LIKE ? ";
146                         push @gParams, "%$sSearch%";
147                     }
148                 } else {
149                     push @gFilters, " $mDataProp LIKE ? ";
150                     push @gParams, "%$sSearch%";
151                 }
152             }
153             $i++;
154         }
155         push @filters, " (" . join(" OR ", @gFilters) . ") ";
156         push @params, @gParams;
157     }
158
159     # Individual filters
160     my $i = 0;
161     while($i < $param->{'iColumns'}) {
162         my $sSearch = $param->{'sSearch_'.$i};
163         if($sSearch) {
164             my $mDataProp = $param->{'mDataProp_'.$i};
165             my @filter_fields = $param->{$mDataProp.'_filteron'}
166                 ? split(' ', $param->{$mDataProp.'_filteron'})
167                 : ();
168             if(@filter_fields > 0) {
169                 my @localfilters;
170                 foreach my $field (@filter_fields) {
171                     push @localfilters, " $field LIKE ? ";
172                     push @params, "%$sSearch%";
173                 }
174                 push @filters, " ( ". join(" OR ", @localfilters) ." ) ";
175             } else {
176                 push @filters, " $mDataProp LIKE ? ";
177                 push @params, "%$sSearch%";
178             }
179         }
180         $i++;
181     }
182
183     return (\@filters, \@params);
184 }
185
186 =head2 dt_get_params
187
188     my %dtparam = = dt_get_params( $input )
189     This function takes a reference to a new CGI object.
190     It prepares a hash containing Datatable parameters.
191
192 =cut
193 sub dt_get_params {
194     my $input = shift;
195     my %dtparam;
196     my $vars = $input->Vars;
197
198     foreach(qw/ iDisplayStart iDisplayLength iColumns sSearch bRegex iSortingCols sEcho /) {
199         $dtparam{$_} = $input->param($_);
200     }
201     foreach(grep /(?:_sorton|_filteron)$/, keys %$vars) {
202         $dtparam{$_} = $vars->{$_};
203     }
204     for(my $i=0; $i<$dtparam{'iColumns'}; $i++) {
205         foreach(qw/ bSearchable sSearch bRegex bSortable iSortCol mDataProp sSortDir /) {
206             my $key = $_ . '_' . $i;
207             $dtparam{$key} = $input->param($key) if defined $input->param($key);
208         }
209     }
210     return %dtparam;
211 }
212
213 =head2 dt_build_query_simple
214
215     my ( $query, $params )= dt_build_query_simple( $value, $field )
216
217     This function takes a value and a field (table.field).
218
219     It returns (undef, []) if not $value.
220     Else, returns a SQL where string and an arrayref containing parameters
221     for the execute method of the statement.
222
223 =cut
224 sub dt_build_query_simple {
225     my ( $value, $field ) = @_;
226     my $query;
227     my @params;
228     if( $value ) {
229         $query .= " AND $field = ? ";
230         push @params, $value;
231     }
232     return ( $query, \@params );
233 }
234
235 =head2 dt_build_query_dates
236
237     my ( $query, $params )= dt_build_query_dates( $datefrom, $dateto, $field)
238
239     This function takes a datefrom, dateto and a field (table.field).
240
241     It returns (undef, []) if not $value.
242     Else, returns a SQL where string and an arrayref containing parameters
243     for the execute method of the statement.
244
245 =cut
246 sub dt_build_query_dates {
247     my ( $datefrom, $dateto, $field ) = @_;
248     my $query;
249     my @params;
250     if ( $datefrom ) {
251         $query .= " AND $field >= ? ";
252         push @params, C4::Dates->new($datefrom)->output('iso');
253     }
254     if ( $dateto ) {
255         $query .= " AND $field <= ? ";
256         push @params, C4::Dates->new($dateto)->output('iso');
257     }
258     return ( $query, \@params );
259 }
260
261 =head2 dt_build_query
262
263     my ( $query, $filter ) = dt_build_query( $type, @params )
264
265     This function takes a value and a list of parameters.
266
267     It calls dt_build_query_dates or dt_build_query_simple fonction of $type.
268
269     $type can be 'simple' or 'rage_dates'.
270
271 =cut
272 sub dt_build_query {
273     my ( $type, @params ) = @_;
274     given ( $type ) {
275         when ( /simple/ ) {
276             return dt_build_query_simple( @params );
277         }
278         when ( /range_dates/ ) {
279             return dt_build_query_dates( @params );
280         }
281     }
282 }
283
284 1;