Bug 17089: Koha::Ratings - Remove DelRating
[koha.git] / 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__