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(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
  32
  33 BEGIN {
  34     @ISA     = qw(Exporter);
  35
  36     @EXPORT = qw(
  37       &GetRating
  38       &AddRating
  39       &ModRating
  40       &DelRating
  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 statement 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
 142 =item * rating_avg_int - average rating of a biblio, rounded to 1dp
 143
 144 =item * rating_total - total number of ratings of a biblio
 145
 146 =item * rating_value - logged-in user's rating of a biblio
 147
 148 =back
 149
 150 =cut
 151
 152 sub GetRating {
 153     my ( $biblionumber, $borrowernumber ) = @_;
 154
 155     my $ratings = Koha::Database->new()->schema->resultset('Rating')->search(
 156         {
 157             biblionumber => $biblionumber,
 158         }
 159     );
 160
 161     my $sum   = $ratings->get_column('rating_value')->sum();
 162     my $total = $ratings->count();
 163
 164     my ( $avg, $avg_int ) = 0;
 165
 166     if ( $sum and $total ) {
 167         eval { $avg = $sum / $total };
 168     }
 169
 170     $avg_int = sprintf( "%.1f", $avg );
 171     $avg     = sprintf( "%.0f", $avg );
 172
 173     my %rating_hash;
 174     $rating_hash{rating_total}   = $total   || 0;
 175     $rating_hash{rating_avg}     = $avg     || 0;
 176     $rating_hash{rating_avg_int} = $avg_int || 0;
 177
 178     if ($borrowernumber) {
 179         my $rating = Koha::Database->new()->schema->resultset('Rating')->find(
 180             {
 181                 biblionumber   => $biblionumber,
 182                 borrowernumber => $borrowernumber,
 183             }
 184         );
 185         return unless $rating;
 186         $rating_hash{'rating_value'} = $rating->rating_value();
 187     }
 188     else {
 189         $rating_hash{rating_value}          = undef;
 190     }
 191
 192     return \%rating_hash;
 193 }
 194
 195 =head2 AddRating
 196
 197     my $rating_hashref = AddRating( $biblionumber, $borrowernumber, $rating_value );
 198
 199 Add a rating for a bib
 200
 201 This adds or updates a rating for a particular user on a biblio. If the value
 202 is 0, then the rating will be deleted. If the value is out of the range of
 203 0-5, nothing will happen.
 204
 205 =cut
 206
 207 sub AddRating {
 208     my ( $biblionumber, $borrowernumber, $rating_value ) = @_;
 209
 210     my $rating = Koha::Database->new()->schema->resultset('Rating')->create(
 211         {
 212             biblionumber   => $biblionumber,
 213             borrowernumber => $borrowernumber,
 214             rating_value   => $rating_value
 215         }
 216     );
 217
 218     return GetRating( $biblionumber, $borrowernumber );
 219 }
 220
 221 =head2 ModRating
 222
 223     my $rating_hashref = ModRating( $biblionumber, $borrowernumber, $rating_value );
 224
 225 Mod a rating for a bib
 226
 227 =cut
 228
 229 sub ModRating {
 230     my ( $biblionumber, $borrowernumber, $rating_value ) = @_;
 231
 232     my $rating = Koha::Database->new()->schema->resultset('Rating')->find(
 233         {
 234             borrowernumber => $borrowernumber,
 235             biblionumber   => $biblionumber
 236         }
 237     );
 238
 239     $rating->update( { rating_value => $rating_value } );
 240
 241     return GetRating( $biblionumber, $borrowernumber );
 242 }
 243
 244 =head2 DelRating
 245
 246     my $rating_hashref = DelRating( $biblionumber, $borrowernumber );
 247
 248 Delete a rating for a bib
 249
 250 =cut
 251
 252 sub DelRating {
 253     my ( $biblionumber, $borrowernumber ) = @_;
 254
 255     my $rating = Koha::Database->new()->schema->resultset('Rating')->find(
 256         {
 257             borrowernumber => $borrowernumber,
 258             biblionumber   => $biblionumber
 259         }
 260     );
 261
 262     $rating->delete() if $rating;
 263
 264     return GetRating($biblionumber);
 265 }
 266
 267 1;
 268 __END__