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