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