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       &DelRating
  39     );
  40 }
  41
  42 =head1 NAME
  43
  44 C4::Ratings - a module to manage user ratings of Koha biblios
  45
  46 =head1 DESCRIPTION
  47
  48 Ratings.pm provides simple functionality for a user to 'rate' a biblio, and to retrieve a biblio's rating info
  49
  50 the 4 subroutines allow a user to add, delete modify and retrieve rating info for a biblio.
  51
  52 The rating can be from 1 to 5 stars, (5 stars being the highest rating)
  53
  54 =head1 SYNOPSIS
  55
  56 Get a rating for a bib
  57  my $rating_hashref = GetRating( $biblionumber, undef );
  58  my $rating_hashref = GetRating( $biblionumber, $borrowernumber );
  59
  60 Delete a rating for a bib
  61  my $rating_hashref = DelRating( $biblionumber, $borrowernumber );
  62
  63
  64 All subroutines in Ratings.pm return a hashref which contain 4 keys
  65
  66 for example, after executing this statement below...
  67
  68     my $rating_hashref = GetRating ( $biblionumber, $borrowernumber ) ;
  69
  70 $rating_hashref now contains a hashref that looks like this...
  71
  72     $rating  = {
  73              rating_avg       => '2',
  74              rating_avg_int   => '2.3',
  75              rating_total     => '432',
  76              rating_value => '5'
  77     }
  78
  79 they 4 keys returned in the hashref are...
  80
  81     rating_avg:            average rating of a biblio
  82     rating_avg_int:        average rating of a biblio, rounded to 1dp
  83     rating_total:          total number of ratings of a biblio
  84     rating_value:          logged-in user's rating of a biblio
  85
  86 =head1 BUGS
  87
  88 Please use bugs.koha-community.org for tracking bugs.
  89
  90 =head1 SOURCE AVAILABILITY
  91
  92 The source is available from the koha-community.org git server
  93 L<http://git.koha-community.org>
  94
  95 =head1 AUTHOR
  96
  97 Original code: Mason James <mtj@kohaaloha.com>
  98
  99 =head1 COPYRIGHT
 100
 101 Copyright (c) 2011 Mason James <mtj@kohaaloha.com>
 102
 103 =head1 LICENSE
 104
 105 C4::Ratings is free software. You can redistribute it and/or
 106 modify it under the same terms as Koha itself.
 107
 108 =head1 CREDITS
 109
 110  Mason James <mtj@kohaaloha.com>
 111  Koha Dev Team <http://koha-community.org>
 112
 113
 114 =head2 GetRating
 115
 116     GetRating($biblionumber, [$borrowernumber])
 117
 118 Get a rating for a bib
 119  my $rating_hashref = GetRating( $biblionumber, undef );
 120  my $rating_hashref = GetRating( $biblionumber, $borrowernumber );
 121
 122 This returns the rating for the supplied biblionumber. It will also return
 123 the rating that the supplied user gave to the provided biblio. If a particular
 124 value can't be supplied, '0' is returned for that value.
 125
 126 =head3 RETURNS
 127
 128 A hashref containing:
 129
 130 =over
 131
 132 =item * rating_avg - average rating of a biblio
 133
 134 =item * rating_avg_int - average rating of a biblio, rounded to 1dp
 135
 136 =item * rating_total - total number of ratings of a biblio
 137
 138 =item * rating_value - logged-in user's rating of a biblio
 139
 140 =back
 141
 142 =cut
 143
 144 sub GetRating {
 145     my ( $biblionumber, $borrowernumber ) = @_;
 146
 147     my $ratings = Koha::Database->new()->schema->resultset('Rating')->search(
 148         {
 149             biblionumber => $biblionumber,
 150         }
 151     );
 152
 153     my $sum   = $ratings->get_column('rating_value')->sum();
 154     my $total = $ratings->count();
 155
 156     my ( $avg, $avg_int ) = 0;
 157
 158     if ( $sum and $total ) {
 159         eval { $avg = $sum / $total };
 160     }
 161
 162     $avg_int = sprintf( "%.1f", $avg );
 163     $avg     = sprintf( "%.0f", $avg );
 164
 165     my %rating_hash;
 166     $rating_hash{rating_total}   = $total   || 0;
 167     $rating_hash{rating_avg}     = $avg     || 0;
 168     $rating_hash{rating_avg_int} = $avg_int || 0;
 169
 170     if ($borrowernumber) {
 171         my $rating = Koha::Database->new()->schema->resultset('Rating')->find(
 172             {
 173                 biblionumber   => $biblionumber,
 174                 borrowernumber => $borrowernumber,
 175             }
 176         );
 177         return unless $rating;
 178         $rating_hash{'rating_value'} = $rating->rating_value();
 179     }
 180     else {
 181         $rating_hash{rating_value}          = undef;
 182     }
 183
 184     return \%rating_hash;
 185 }
 186
 187 =head2 DelRating
 188
 189     my $rating_hashref = DelRating( $biblionumber, $borrowernumber );
 190
 191 Delete a rating for a bib
 192
 193 =cut
 194
 195 sub DelRating {
 196     my ( $biblionumber, $borrowernumber ) = @_;
 197
 198     my $rating = Koha::Database->new()->schema->resultset('Rating')->find(
 199         {
 200             borrowernumber => $borrowernumber,
 201             biblionumber   => $biblionumber
 202         }
 203     );
 204
 205     $rating->delete() if $rating;
 206
 207     return GetRating($biblionumber);
 208 }
 209
 210 1;
 211 __END__