bug 8215: (followup) make sure C4::CourseReserves doesn't export anything
[koha.git] / C4 / Ratings.pm
1 package C4::Ratings;
2
3 # Copyright 2011 KohaAloha, NZ
4 # Parts copyright 2011, Catalyst IT, NZ.
5 #
6 # This file is part of Koha.
7 #
8 # Koha is free software; you can redistribute it and/or modify it under the
9 # terms of the GNU General Public License as published by the Free Software
10 # Foundation; either version 2 of the License, or (at your option) any later
11 # version.
12 #
13 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
14 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
15 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
16 #
17 # You should have received a copy of the GNU General Public License along
18 # with Koha; if not, write to the Free Software Foundation, Inc.,
19 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
20
21 use strict;
22 use warnings;
23 use Carp;
24 use Exporter;
25 use POSIX;
26 use C4::Debug;
27 use C4::Context;
28
29 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
30
31 BEGIN {
32     $VERSION = 3.07.00.049;
33     @ISA     = qw(Exporter);
34
35     @EXPORT = qw(
36       &GetRating
37       &AddRating
38       &ModRating
39       &DelRating
40     );
41 }
42
43 =head1 NAME
44
45 C4::Ratings - a module to manage user ratings of Koha biblios
46
47 =head1 DESCRIPTION
48
49 Ratings.pm provides simple functionality for a user to 'rate' a biblio, and to retrieve a biblio's rating info
50
51 the 4 subroutines allow a user to add, delete modify and retrieve rating info for a biblio.
52
53 The rating can be from 1 to 5 stars, (5 stars being the highest rating)
54
55 =head1 SYNOPSIS
56
57 Get a rating for a bib
58  my $rating_hashref = GetRating( $biblionumber, undef );
59  my $rating_hashref = GetRating( $biblionumber, $borrowernumber );
60
61 Add a rating for a bib
62  my $rating_hashref = AddRating( $biblionumber, $borrowernumber, $rating_value );
63
64 Mod a rating for a bib
65  my $rating_hashref = ModRating( $biblionumber, $borrowernumber, $rating_value );
66
67 Delete a rating for a bib
68  my $rating_hashref = DelRating( $biblionumber, $borrowernumber );
69
70
71 All subroutines in Ratings.pm return a hashref which contain 4 keys
72
73 for example, after executing this statment below...
74
75     my $rating_hashref = GetRating ( $biblionumber, $borrowernumber ) ;
76
77 $rating_hashref now contains a hashref that looks like this...
78
79     $rating  = {
80              rating_avg       => '2',
81              rating_avg_int   => '2.3',
82              rating_total     => '432',
83              rating_value => '5'
84     }
85
86 they 4 keys returned in the hashref are...
87
88     rating_avg:            average rating of a biblio
89     rating_avg_int:        average rating of a biblio, rounded to 1dp
90     rating_total:          total number of ratings of a biblio
91     rating_value:          logged-in user's rating of a biblio
92
93 =head1 BUGS
94
95 Please use bugs.koha-community.org for tracking bugs.
96
97 =head1 SOURCE AVAILABILITY
98
99 The source is available from the koha-community.org git server
100 L<http://git.koha-community.org>
101
102 =head1 AUTHOR
103
104 Original code: Mason James <mtj@kohaaloha.com>
105
106 =head1 COPYRIGHT
107
108 Copyright (c) 2011 Mason James <mtj@kohaaloha.com>
109
110 =head1 LICENSE
111
112 C4::Ratings is free software. You can redistribute it and/or
113 modify it under the same terms as Koha itself.
114
115 =head1 CREDITS
116
117  Mason James <mtj@kohaaloha.com>
118  Koha Dev Team <http://koha-community.org>
119
120
121 =head2 GetRating
122
123     GetRating($biblionumber, [$borrowernumber])
124
125 Get a rating for a bib
126  my $rating_hashref = GetRating( $biblionumber, undef );
127  my $rating_hashref = GetRating( $biblionumber, $borrowernumber );
128
129 This returns the rating for the supplied biblionumber. It will also return
130 the rating that the supplied user gave to the provided biblio. If a particular
131 value can't be supplied, '0' is returned for that value.
132
133 =head3 RETURNS
134
135 A hashref containing:
136
137 =over
138
139 =item * rating_avg - average rating of a biblio
140 =item * rating_avg_int - average rating of a biblio, rounded to 1dp
141 =item * rating_total - total number of ratings of a biblio
142 =item * rating_value - logged-in user's rating of a biblio
143
144 =back
145
146 =cut
147
148 sub GetRating {
149     my ( $biblionumber, $borrowernumber ) = @_;
150     my $query = qq| SELECT COUNT(*) AS total, SUM(rating_value) AS sum
151 FROM ratings WHERE biblionumber = ? |;
152
153     my $sth = C4::Context->dbh->prepare($query);
154     $sth->execute($biblionumber);
155     my $res = $sth->fetchrow_hashref();
156
157     my ( $avg, $avg_int ) = 0;
158
159     if ( $res->{sum} and $res->{total} ) {
160         eval { $avg = $res->{sum} / $res->{total} };
161     }
162
163     $avg_int = sprintf( "%.1f", $avg );
164     $avg     = sprintf( "%.0f", $avg );
165
166     my %rating_hash;
167     $rating_hash{rating_total}   = $res->{total} || 0;
168     $rating_hash{rating_avg}     = $avg || 0;
169     $rating_hash{rating_avg_int} = $avg_int ||0;
170
171     if ($borrowernumber) {
172         my $q2 = qq|
173 SELECT rating_value FROM ratings WHERE biblionumber = ? AND borrowernumber = ?|;
174         my $sth1 = C4::Context->dbh->prepare($q2);
175         $sth1->execute( $biblionumber, $borrowernumber );
176         my $res1 = $sth1->fetchrow_hashref();
177         $rating_hash{'rating_value'} = $res1->{"rating_value"};
178     }
179     else {
180         $rating_hash{rating_borrowernumber} = undef;
181         $rating_hash{rating_value}          = undef;
182     }
183
184 #### %rating_hash
185     return \%rating_hash;
186 }
187
188 =head2 AddRating
189
190     my $rating_hashref = AddRating( $biblionumber, $borrowernumber, $rating_value );
191
192 Add a rating for a bib
193
194 This adds or updates a rating for a particular user on a biblio. If the value
195 is 0, then the rating will be deleted. If the value is out of the range of
196 0-5, nothing will happen.
197
198 =cut
199
200 sub AddRating {
201     my ( $biblionumber, $borrowernumber, $rating_value ) = @_;
202     my $query =
203       qq| INSERT INTO ratings (borrowernumber,biblionumber,rating_value)
204         VALUES (?,?,?)|;
205     my $sth = C4::Context->dbh->prepare($query);
206     $sth->execute( $borrowernumber, $biblionumber, $rating_value );
207     my $rating = GetRating( $biblionumber, $borrowernumber );
208     return $rating;
209 }
210
211 =head2 ModRating
212
213     my $rating_hashref = ModRating( $biblionumber, $borrowernumber, $rating_value );
214
215 Mod a rating for a bib
216
217 =cut
218
219 sub ModRating {
220     my ( $biblionumber, $borrowernumber, $rating_value ) = @_;
221     my $query =
222 qq|UPDATE ratings SET rating_value = ? WHERE borrowernumber = ? AND biblionumber = ?|;
223     my $sth = C4::Context->dbh->prepare($query);
224     $sth->execute( $rating_value, $borrowernumber, $biblionumber );
225     my $rating = GetRating( $biblionumber, $borrowernumber );
226     return $rating;
227 }
228
229 =head2 DelRating
230
231     my $rating_hashref = DelRating( $biblionumber, $borrowernumber );
232
233 Delete a rating for a bib
234
235 =cut
236
237 sub DelRating {
238     my ( $biblionumber, $borrowernumber ) = @_;
239     my $dbh = C4::Context->dbh;
240     my $query =
241       "delete from ratings where borrowernumber = ? and biblionumber = ?";
242     my $sth    = C4::Context->dbh->prepare($query);
243     my $rv     = $sth->execute( $borrowernumber, $biblionumber );
244     my $rating = GetRating( $biblionumber, undef );
245     return $rating;
246 }
247
248 1;
249 __END__