[Koha-cvs] koha/C4 Suggestions.pm

[Antoine Farnault]

CVSROOT:        /sources/koha
Module name:    koha
Changes by:     Antoine Farnault <toins>        06/07/12 08:15:46

Modified files:
        C4             : Suggestions.pm 

Log message:
        Code cleaning :
        POD rewrited

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/koha/C4/Suggestions.pm?cvsroot=koha&r1=1.11&r2=1.12

Patches:
Index: Suggestions.pm
===================================================================
RCS file: /sources/koha/koha/C4/Suggestions.pm,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -b -r1.11 -r1.12
--- Suggestions.pm      7 Jul 2006 08:44:57 -0000       1.11
+++ Suggestions.pm      12 Jul 2006 08:15:46 -0000      1.12
@@ -17,7 +17,7 @@
 # Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
 # Suite 330, Boston, MA  02111-1307 USA
 
-# $Id: Suggestions.pm,v 1.11 2006/07/07 08:44:57 toins Exp $
+# $Id: Suggestions.pm,v 1.12 2006/07/12 08:15:46 toins Exp $
 
 use strict;
 require Exporter;
@@ -28,7 +28,7 @@
 use vars qw($VERSION @ISA @EXPORT);
 
 # set the version for version checking
-$VERSION = do { my @v = '$Revision: 1.11 $' =~ /\d+/g;
+$VERSION = do { my @v = '$Revision: 1.12 $' =~ /\d+/g;
   shift(@v) . "." . join("_", map {sprintf "%03d", $_ } @v); };
 
 =head1 NAME
@@ -41,19 +41,24 @@
 
 =head1 DESCRIPTION
 
-The functions in this module deal with the suggestions :
-* in OPAC
-* in librarian interface
+=over 4
+
+The functions in this module deal with the suggestions in OPAC and in 
librarian interface
 
 A suggestion is done in the OPAC. It has the status "ASKED"
-When a librarian manages the suggestion, he can set the status to "REJECTED" 
or "ORDERED".
+
+When a librarian manages the suggestion, he can set the status to "REJECTED" 
or "ACCEPTED".
+
+When the book is ordered, the suggestion status becomes "ORDERED"
+
 When a book is ordered and arrived in the library, the status becomes 
"AVAILABLE"
-All suggestions of a borrower by the borrower itself.
-Suggestions done by other can be seen when not "AVAILABLE"
 
-=head1 FUNCTIONS
+All suggestions of a borrower can be seen by the borrower itself.
+Suggestions done by other borrowers can be seen when not "AVAILABLE"
 
-=over 2
+=back
+
+=head1 FUNCTIONS
 
 =cut
 
@@ -69,13 +74,13 @@
     &GetSuggestionFromBiblionumber
  );
 
-=item SearchSuggestion
+=head2 SearchSuggestion
 
-(address@hidden) = &SearchSuggestion($user)
+=over 4
 
-searches for a suggestion
+(address@hidden) = 
&SearchSuggestion($user,$author,$title,$publishercode,$status,$suggestedbyme)
 
-C<$user> is the user code (used as suggestor filter)
+searches for a suggestion
 
 return :
 C<address@hidden> : the suggestions found. Array of hash.
@@ -83,7 +88,10 @@
 * in the status field
 * as parameter ( for example ASKED => 1, or REJECTED => 1) . This is for 
template & translation purposes.
 
+=back
+
 =cut
+
 sub SearchSuggestion  {
     my 
($user,$author,$title,$publishercode,$status,$suggestedbyme)address@hidden;
     my $dbh = C4::Context->dbh;
@@ -126,8 +134,7 @@
         }
     }
     if ($suggestedbyme) {
-        if ($suggestedbyme eq -1) {        # FIXME ! what's this strange code ?
-        } else {
+        unless ($suggestedbyme eq -1) {
             push @sql_params,$user;
             $query .= " and suggestedby=?";
         }
@@ -151,34 +158,19 @@
     return (address@hidden);
 }
 
-=item NewSuggestion
-
-&NewSuggestion($borrowernumber,$title,$author,$publishercode,$note,$copyrightdate,$volumedesc,$publicationyear,$place,$isbn,$biblionumber)
+=head2 GetSuggestion
 
-Insert a new suggestion on database with value given on input arg.
-
-=cut
-sub NewSuggestion {
-    my 
($borrowernumber,$title,$author,$publishercode,$note,$copyrightdate,$volumedesc,$publicationyear,$place,$isbn,$biblionumber)
 = @_;
-    my $dbh = C4::Context->dbh;
-    my $query = qq |
-        INSERT INTO suggestions
-            (status,suggestedby,title,author,publishercode,note,copyrightdate,
-            volumedesc,publicationyear,place,isbn,biblionumber)
-        VALUES ('ASKED',?,?,?,?,?,?,?,?,?,?,?)
-    |;
-    my $sth = $dbh->prepare($query);
-    
$sth->execute($borrowernumber,$title,$author,$publishercode,$note,$copyrightdate,$volumedesc,$publicationyear,$place,$isbn,$biblionumber);
-}
-
-=item GetSuggestion
+=over 4
 
 \%sth = &GetSuggestion($suggestionid)
 
-this function get a suggestion from $suggestionid given on input arg.
+this function get the detail of the suggestion $suggestionid (input arg)
 
 return :
     the result of the SQL query as a hash : $sth->fetchrow_hashref.
+
+=back
+
 =cut
 sub GetSuggestion {
     my ($suggestionid) = @_;
@@ -193,43 +185,64 @@
     return($sth->fetchrow_hashref);
 }
 
-=item DelSuggestion
+=head2 GetSuggestionFromBiblionumber
 
-&DelSuggestion($borrowernumber,$suggestionid)
+=over 4
 
-Delete a suggestion. A borrower can delete a suggestion only if he is its 
owner.
+$suggestionid = &GetSuggestionFromBiblionumber($dbh,$biblionumber)
+
+Get a suggestion from it's biblionumber.
+
+return :
+the id of the suggestion which is related to the biblionumber given on input 
args.
+
+=back
 
 =cut
-sub DelSuggestion {
-    my ($borrowernumber,$suggestionid) = @_;
-    my $dbh = C4::Context->dbh;
-    # check that the suggestion comes from the suggestor
-    my $query = qq |
-        SELECT suggestedby
+sub GetSuggestionFromBiblionumber {
+    my ($dbh,$biblionumber) = @_;
+    my $query = qq|
+        SELECT suggestionid
         FROM   suggestions
-        WHERE  suggestionid=?
+        WHERE  biblionumber=?
     |;
     my $sth = $dbh->prepare($query);
-    $sth->execute($suggestionid);
-    my ($suggestedby) = $sth->fetchrow;
-    if ($suggestedby eq $borrowernumber) {
-        my $queryDelete = qq|
-            DELETE FROM suggestions
-            WHERE suggestionid=?
-        |;
-        $sth = $dbh->prepare($queryDelete);
-        $sth->execute($suggestionid);
-    }
+    $sth->execute($biblionumber);
+    my ($suggestionid) = $sth->fetchrow;
+    return $suggestionid;
 }
-=item CountSuggestion
+
+
+=head2 CountSuggestion
+
+=over 4
 
 &CountSuggestion($status)
 
 Count the number of suggestions with the status given on input argument.
+the arg status can be :
+
+=over
+
+=over
+
+=item * ASKED : asked by the user, not dealed by the librarian
+
+=item * ACCEPTED : accepted by the librarian, but not yet ordered
+
+=item * REJECTED : rejected by the librarian (definitive status)
+
+=item * ORDERED : ordered by the librarian (acquisition module)
+
+=back
+
+=back
 
 return :
 the number of suggestion with this status.
 
+=back
+
 =cut
 sub CountSuggestion {
     my ($status) = @_;
@@ -271,12 +284,44 @@
     return $result;
 }
 
-=item ModStatus
+=head2 NewSuggestion
+
+
+=over 4
+
+&NewSuggestion($borrowernumber,$title,$author,$publishercode,$note,$copyrightdate,$volumedesc,$publicationyear,$place,$isbn,$biblionumber)
+
+Insert a new suggestion on database with value given on input arg.
+
+=back
+
+=cut
+sub NewSuggestion {
+    my 
($borrowernumber,$title,$author,$publishercode,$note,$copyrightdate,$volumedesc,$publicationyear,$place,$isbn,$biblionumber)
 = @_;
+    my $dbh = C4::Context->dbh;
+    my $query = qq |
+        INSERT INTO suggestions
+            (status,suggestedby,title,author,publishercode,note,copyrightdate,
+            volumedesc,publicationyear,place,isbn,biblionumber)
+        VALUES ('ASKED',?,?,?,?,?,?,?,?,?,?,?)
+    |;
+    my $sth = $dbh->prepare($query);
+    
$sth->execute($borrowernumber,$title,$author,$publishercode,$note,$copyrightdate,$volumedesc,$publicationyear,$place,$isbn,$biblionumber);
+}
+
+=head2 ModStatus
+
+=over 4
 
 &ModStatus($suggestionid,$status,$managedby,$biblionumber)
 
-Modify the status (status can be 'ASKED', 'ACCEPTED', 'REJECTED'...)
-and send a mail to notify the librarian.
+Modify the status (status can be 'ASKED', 'ACCEPTED', 'REJECTED', 'ORDERED')
+and send a mail to notify the user that did the suggestion.
+
+Note that there is no function to modify a suggestion : only the status can be 
modified, thus the name of the function.
+
+=back
+
 =cut
 sub ModStatus {
     my ($suggestionid,$status,$managedby,$biblionumber) = @_;
@@ -358,33 +403,15 @@
     );
     sendmail(%mail);
 }
-=item GetSuggestionFromBiblionumber
 
-$suggestionid = &GetSuggestionFromBiblionumber($dbh,$biblionumber)
-
-Get a suggestion from the biblionumber.
-
-return :
- the id of the suggestion which has the biblionumber given on input args.
-
-=cut
-sub GetSuggestionFromBiblionumber {
-    my ($dbh,$biblionumber) = @_;
-    my $query = qq|
-        SELECT suggestionid
-        FROM   suggestions
-        WHERE  biblionumber=?
-    |;
-    my $sth = $dbh->prepare($query);
-    $sth->execute($biblionumber);
-    my ($suggestionid) = $sth->fetchrow;
-    return $suggestionid;
-}
-=item ConnectSuggestionAndBiblio
+=head2 ConnectSuggestionAndBiblio
 
+=over 4
 &ConnectSuggestionAndBiblio($suggestionid,$biblionumber)
 
- connect a suggestion to an existing biblio
+connect a suggestion to an existing biblio
+
+=back
 
 =cut
 sub ConnectSuggestionAndBiblio {
@@ -398,8 +425,37 @@
     my $sth = $dbh->prepare($query);
     $sth->execute($biblionumber,$suggestionid);
 }
-=back
 
-=head1 SEE ALSO
+=head2 DelSuggestion
+
+=over 4
+
+&DelSuggestion($borrowernumber,$suggestionid)
+
+Delete a suggestion. A borrower can delete a suggestion only if he is its 
owner.
+
+=back
 
 =cut
+
+sub DelSuggestion {
+    my ($borrowernumber,$suggestionid) = @_;
+    my $dbh = C4::Context->dbh;
+    # check that the suggestion comes from the suggestor
+    my $query = qq |
+        SELECT suggestedby
+        FROM   suggestions
+        WHERE  suggestionid=?
+    |;
+    my $sth = $dbh->prepare($query);
+    $sth->execute($suggestionid);
+    my ($suggestedby) = $sth->fetchrow;
+    if ($suggestedby eq $borrowernumber) {
+        my $queryDelete = qq|
+            DELETE FROM suggestions
+            WHERE suggestionid=?
+        |;
+        $sth = $dbh->prepare($queryDelete);
+        $sth->execute($suggestionid);
+    }
+}
\ No newline at end of file