Adding a feature to export star_ratings data
[koha:mainline.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       AllRatings
41     );
42 }
43
44 =head1 NAME
45
46 C4::Ratings - a module to manage user ratings of Koha biblios
47
48 =head1 DESCRIPTION
49
50 Ratings.pm provides simple functionality for a user to 'rate' a biblio, and to retrieve a biblio's rating info
51
52 the 4 subroutines allow a user to add, delete modify and retrieve rating info for a biblio.
53
54 The rating can be from 1 to 5 stars, (5 stars being the highest rating)
55
56 =head1 SYNOPSIS
57
58 Get a rating for a bib
59  my $rating_hashref = GetRating( $biblionumber, undef );
60  my $rating_hashref = GetRating( $biblionumber, $borrowernumber );
61
62 Add a rating for a bib
63  my $rating_hashref = AddRating( $biblionumber, $borrowernumber, $rating_value );
64
65 Mod a rating for a bib
66  my $rating_hashref = ModRating( $biblionumber, $borrowernumber, $rating_value );
67
68 Delete a rating for a bib
69  my $rating_hashref = DelRating( $biblionumber, $borrowernumber );
70
71
72 All subroutines in Ratings.pm return a hashref which contain 4 keys
73
74 for example, after executing this statment below...
75
76     my $rating_hashref = GetRating ( $biblionumber, $borrowernumber ) ;
77
78 $rating_hashref now contains a hashref that looks like this...
79
80     $rating  = {
81              rating_avg       => '2',
82              rating_avg_int   => '2.3',
83              rating_total     => '432',
84              rating_value => '5'
85     }
86
87 they 4 keys returned in the hashref are...
88
89     rating_avg:            average rating of a biblio
90     rating_avg_int:        average rating of a biblio, rounded to 1dp
91     rating_total:          total number of ratings of a biblio
92     rating_value:          logged-in user's rating of a biblio
93
94 =head1 BUGS
95
96 Please use bugs.koha-community.org for tracking bugs.
97
98 =head1 SOURCE AVAILABILITY
99
100 The source is available from the koha-community.org git server
101 L<http://git.koha-community.org>
102
103 =head1 AUTHOR
104
105 Original code: Mason James <mtj@kohaaloha.com>
106
107 =head1 COPYRIGHT
108
109 Copyright (c) 2011 Mason James <mtj@kohaaloha.com>
110
111 =head1 LICENSE
112
113 C4::Ratings is free software. You can redistribute it and/or
114 modify it under the same terms as Koha itself.
115
116 =head1 CREDITS
117
118  Mason James <mtj@kohaaloha.com>
119  Koha Dev Team <http://koha-community.org>
120
121
122 =head2 GetRating
123
124     GetRating($biblionumber, [$borrowernumber])
125
126 Get a rating for a bib
127  my $rating_hashref = GetRating( $biblionumber, undef );
128  my $rating_hashref = GetRating( $biblionumber, $borrowernumber );
129
130 This returns the rating for the supplied biblionumber. It will also return
131 the rating that the supplied user gave to the provided biblio. If a particular
132 value can't be supplied, '0' is returned for that value.
133
134 =head3 RETURNS
135
136 A hashref containing:
137
138 =over
139
140 =item * rating_avg - average rating of a biblio
141 =item * rating_avg_int - average rating of a biblio, rounded to 1dp
142 =item * rating_total - total number of ratings of a biblio
143 =item * rating_value - logged-in user's rating of a biblio
144
145 =back
146
147 =cut
148
149 sub GetRating {
150     my ( $biblionumber, $borrowernumber ) = @_;
151     my $query = qq| SELECT COUNT(*) AS total, SUM(rating_value) AS sum
152 FROM ratings WHERE biblionumber = ? |;
153
154     my $sth = C4::Context->dbh->prepare($query);
155     $sth->execute($biblionumber);
156     my $res = $sth->fetchrow_hashref();
157
158     my ( $avg, $avg_int ) = 0;
159
160     if ( $res->{sum} and $res->{total} ) {
161         eval { $avg = $res->{sum} / $res->{total} };
162     }
163
164     $avg_int = sprintf( "%.1f", $avg );
165     $avg     = sprintf( "%.0f", $avg );
166
167     my %rating_hash;
168     $rating_hash{rating_total}   = $res->{total} || 0;
169     $rating_hash{rating_avg}     = $avg || 0;
170     $rating_hash{rating_avg_int} = $avg_int ||0;
171
172     if ($borrowernumber) {
173         my $q2 = qq|
174 SELECT rating_value FROM ratings WHERE biblionumber = ? AND borrowernumber = ?|;
175         my $sth1 = C4::Context->dbh->prepare($q2);
176         $sth1->execute( $biblionumber, $borrowernumber );
177         my $res1 = $sth1->fetchrow_hashref();
178         $rating_hash{'rating_value'} = $res1->{"rating_value"};
179     }
180     else {
181         $rating_hash{rating_borrowernumber} = undef;
182         $rating_hash{rating_value}          = undef;
183     }
184
185 #### %rating_hash
186     return \%rating_hash;
187 }
188
189 =head2 AddRating
190
191     my $rating_hashref = AddRating( $biblionumber, $borrowernumber, $rating_value );
192
193 Add a rating for a bib
194
195 This adds or updates a rating for a particular user on a biblio. If the value
196 is 0, then the rating will be deleted. If the value is out of the range of
197 0-5, nothing will happen.
198
199 =cut
200
201 sub AddRating {
202     my ( $biblionumber, $borrowernumber, $rating_value ) = @_;
203     my $query =
204       qq| INSERT INTO ratings (borrowernumber,biblionumber,rating_value)
205         VALUES (?,?,?)|;
206     my $sth = C4::Context->dbh->prepare($query);
207     $sth->execute( $borrowernumber, $biblionumber, $rating_value );
208     my $rating = GetRating( $biblionumber, $borrowernumber );
209     return $rating;
210 }
211
212 =head2 ModRating
213
214     my $rating_hashref = ModRating( $biblionumber, $borrowernumber, $rating_value );
215
216 Mod a rating for a bib
217
218 =cut
219
220 sub ModRating {
221     my ( $biblionumber, $borrowernumber, $rating_value ) = @_;
222     my $query =
223 qq|UPDATE ratings SET rating_value = ? WHERE borrowernumber = ? AND biblionumber = ?|;
224     my $sth = C4::Context->dbh->prepare($query);
225     $sth->execute( $rating_value, $borrowernumber, $biblionumber );
226     my $rating = GetRating( $biblionumber, $borrowernumber );
227     return $rating;
228 }
229
230 =head2 DelRating
231
232     my $rating_hashref = DelRating( $biblionumber, $borrowernumber );
233
234 Delete a rating for a bib
235
236 =cut
237
238 sub DelRating {
239     my ( $biblionumber, $borrowernumber ) = @_;
240     my $dbh = C4::Context->dbh;
241     my $query =
242       "delete from ratings where borrowernumber = ? and biblionumber = ?";
243     my $sth    = C4::Context->dbh->prepare($query);
244     my $rv     = $sth->execute( $borrowernumber, $biblionumber );
245     my $rating = GetRating( $biblionumber, undef );
246     return $rating;
247 }
248
249 =head2 AllRatings
250
251     my $rating_arrayref = AllRatings();
252
253 Get all ratings with isbn or issn, title and author
254
255 =cut
256
257 sub AllRatings {
258     my $dbh = C4::Context->dbh;
259     my $query =
260 "SELECT AVG(rating_value) AS rating,ratings.biblionumber,title FROM ratings LEFT JOIN biblio ON (biblio.biblionumber = ratings.biblionumber) GROUP by ratings.biblionumber";
261     my $sth = $dbh->prepare($query);
262     $sth->execute();
263     my $results = $sth->fetchall_arrayref( {} );
264     return $results;
265 }
266 1;
267 __END__