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