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.00;
  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__