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       &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 Mod a rating for a bib
  62  my $rating_hashref = ModRating( $biblionumber, $borrowernumber, $rating_value );
  63
  64 Delete a rating for a bib
  65  my $rating_hashref = DelRating( $biblionumber, $borrowernumber );
  66
  67
  68 All subroutines in Ratings.pm return a hashref which contain 4 keys
  69
  70 for example, after executing this statement below...
  71
  72     my $rating_hashref = GetRating ( $biblionumber, $borrowernumber ) ;
  73
  74 $rating_hashref now contains a hashref that looks like this...
  75
  76     $rating  = {
  77              rating_avg       => '2',
  78              rating_avg_int   => '2.3',
  79              rating_total     => '432',
  80              rating_value => '5'
  81     }
  82
  83 they 4 keys returned in the hashref are...
  84
  85     rating_avg:            average rating of a biblio
  86     rating_avg_int:        average rating of a biblio, rounded to 1dp
  87     rating_total:          total number of ratings of a biblio
  88     rating_value:          logged-in user's rating of a biblio
  89
  90 =head1 BUGS
  91
  92 Please use bugs.koha-community.org for tracking bugs.
  93
  94 =head1 SOURCE AVAILABILITY
  95
  96 The source is available from the koha-community.org git server
  97 L<http://git.koha-community.org>
  98
  99 =head1 AUTHOR
 100
 101 Original code: Mason James <mtj@kohaaloha.com>
 102
 103 =head1 COPYRIGHT
 104
 105 Copyright (c) 2011 Mason James <mtj@kohaaloha.com>
 106
 107 =head1 LICENSE
 108
 109 C4::Ratings is free software. You can redistribute it and/or
 110 modify it under the same terms as Koha itself.
 111
 112 =head1 CREDITS
 113
 114  Mason James <mtj@kohaaloha.com>
 115  Koha Dev Team <http://koha-community.org>
 116
 117
 118 =head2 GetRating
 119
 120     GetRating($biblionumber, [$borrowernumber])
 121
 122 Get a rating for a bib
 123  my $rating_hashref = GetRating( $biblionumber, undef );
 124  my $rating_hashref = GetRating( $biblionumber, $borrowernumber );
 125
 126 This returns the rating for the supplied biblionumber. It will also return
 127 the rating that the supplied user gave to the provided biblio. If a particular
 128 value can't be supplied, '0' is returned for that value.
 129
 130 =head3 RETURNS
 131
 132 A hashref containing:
 133
 134 =over
 135
 136 =item * rating_avg - average rating of a biblio
 137
 138 =item * rating_avg_int - average rating of a biblio, rounded to 1dp
 139
 140 =item * rating_total - total number of ratings of a biblio
 141
 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 ModRating
 192
 193     my $rating_hashref = ModRating( $biblionumber, $borrowernumber, $rating_value );
 194
 195 Mod a rating for a bib
 196
 197 =cut
 198
 199 sub ModRating {
 200     my ( $biblionumber, $borrowernumber, $rating_value ) = @_;
 201
 202     my $rating = Koha::Database->new()->schema->resultset('Rating')->find(
 203         {
 204             borrowernumber => $borrowernumber,
 205             biblionumber   => $biblionumber
 206         }
 207     );
 208
 209     $rating->update( { rating_value => $rating_value } );
 210
 211     return GetRating( $biblionumber, $borrowernumber );
 212 }
 213
 214 =head2 DelRating
 215
 216     my $rating_hashref = DelRating( $biblionumber, $borrowernumber );
 217
 218 Delete a rating for a bib
 219
 220 =cut
 221
 222 sub DelRating {
 223     my ( $biblionumber, $borrowernumber ) = @_;
 224
 225     my $rating = Koha::Database->new()->schema->resultset('Rating')->find(
 226         {
 227             borrowernumber => $borrowernumber,
 228             biblionumber   => $biblionumber
 229         }
 230     );
 231
 232     $rating->delete() if $rating;
 233
 234     return GetRating($biblionumber);
 235 }
 236
 237 1;
 238 __END__