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