[Koha-cvs] CVS: koha/C4 Letters.pm,NONE,1.1

[Paul POULAIN]

Update of /cvsroot/koha/koha/C4
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv3043/C4

Added Files:
        Letters.pm 
Log Message:
Letters / alert system, continuing...
* adding a package Letters.pm, that manages Letters & alerts.
* adding feature : it's now possible to define a "letter" for any subscription 
created. If a letter is defined, users in OPAC can put an alert on the 
subscription. When an issue is marked "arrived", all users in the alert will 
recieve a mail (as defined in the "letter"). This last part (= send the mail) 
is not yet developped. (Should be done this week)
* adding feature : it's now possible to "put to an alert" in OPAC, for any 
serial subscription. The alert is stored in a new table, called alert. An alert 
can be put only if the librarian has activated them in subscription (and they 
activate it just by choosing a "letter" to sent to borrowers on new issues)
* adding feature : librarian can see in borrower detail which alerts they have 
put, and a user can see in opac-detail which alert they have put too.
Note that the system should be generic enough to manage any type of alert.
I plan to extend it soon to virtual shelves : a borrower will be able to put an 
alert on a virtual shelf, to be warned when something is changed in the virtual 
shelf (mail being sent once a day by cron, or manually by the shelf owner. 
Anyway, a mail won't be sent on every change, users would be spammed by Koha 
;-) )

--- NEW FILE ---
package C4::Letters;


# Copyright 2000-2002 Katipo Communications
#
# This file is part of Koha.
#
# Koha is free software; you can redistribute it and/or modify it under the
# terms of the GNU General Public License as published by the Free Software
# Foundation; either version 2 of the License, or (at your option) any later
# version.
#
# Koha is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along with
# Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
# Suite 330, Boston, MA  02111-1307 USA

use strict;
use C4::Date;
use Date::Manip;
use C4::Suggestions;
require Exporter;

use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);

# set the version for version checking
$VERSION = 0.01;

=head1 NAME

C4::Letters - Give functions for Letters management

=head1 SYNOPSIS

  use C4::Letters;

=head1 DESCRIPTION

  "Letters" is the tool used in Koha to manage informations sent to the patrons 
and/or the library. This include some cron jobs like
  late issues, as well as other tasks like sending a mail to users that have 
subscribed to a "serial issue alert" (= being warned every time a new issue has 
arrived at the library)
  
  Letters are managed through "alerts" sent by Koha on some events. All "alert" 
related functions are in this module too.

=cut

@ISA = qw(Exporter);
@EXPORT = qw(&GetLetterList &addalert &getalert &delalert &findrelatedto);

=head2 GetLetterList

        parameter : $module : the name of the module
        This sub returns an array of hashes with all letters from a given module
        Each hash entry contains :
        - module : the module name
        - code : the code of the letter, char(20)
        - name : the complete name of the letter, char(200)
        - title : the title that will be used as "subject" in mails, char(200)
        - content : the content of the letter. Each field to be replaced by a 
value at runtime is enclosed in << and >>. The fields usually have the same 
name as in the DB 

=cut

sub GetLetterList {
        my ($module) = @_;
        my $dbh = C4::Context->dbh;
        my $sth = $dbh->prepare("select * from letter where module=?");
        $sth->execute($module);
        my @result;
        while (my $line = $sth->fetchrow_hashref) {
                push @result,$line;
        }
        return @result;
}

=head2 addalert

        parameters : 
        - $borrowernumber : the number of the borrower subscribing to the alert
        - $type : the type of alert.
        - externalid : the primary key of the object to put alert on. For 
issues, the alert is made on subscriptionid.

        create an alert and return the alertid (primary key)
        
=cut

sub addalert {
        my ($borrowernumber,$type,$externalid) = @_;
        my $dbh=C4::Context->dbh;
        my $sth = $dbh->prepare("insert into alert (borrowernumber, type, 
externalid) values (?,?,?)");
        $sth->execute($borrowernumber,$type,$externalid);
        # get the alert number newly created and return it
        my $alertid = $dbh->{'mysql_insertid'};
        return $alertid;
}

=head2 delalert
        parameters :
        - alertid : the alert id
        deletes the alert
=cut

sub delalert {
        my ($alertid)address@hidden;
#       warn "ALERTID : $alertid";
        my $dbh = C4::Context->dbh;
        my $sth = $dbh->prepare("delete from alert where alertid=?");
        $sth->execute($alertid);
}

=head2 getalert

        parameters :
        - $borrowernumber : the number of the borrower subscribing to the alert
        - $type : the type of alert.
        - externalid : the primary key of the object to put alert on. For 
issues, the alert is made on subscriptionid.
        all parameters NON mandatory. If a parameter is omitted, the query is 
done without the corresponding parameter. For example, without $externalid, 
returns all alerts for a borrower on a topic.
        
=cut

sub getalert {
        my ($borrowernumber,$type,$externalid) = @_;
        my $dbh=C4::Context->dbh;
        my $query = "select * from alert where";
        my @bind;
        if ($borrowernumber) {
                $query .= " borrowernumber=? and";
                push @bind,$borrowernumber;
        }
        if ($type) {
                $query .= " type=? and";
                push @bind,$type;
        }
        if ($externalid) {
                $query .= " externalid=? and";
                push @bind,$externalid;
        }
        $query =~ s/ and$//;
#       warn "Q : $query";
        my $sth = $dbh->prepare($query);
        $sth->execute(@bind);
        my @result;
        while (my $line = $sth->fetchrow_hashref) {
                push @result,$line;
        }
        return address@hidden if $#result >=0; # return only if there is one 
result.
        return;
}
=head2 findrelatedto
        parameters :
        - $type : the type of alert
        - $externalid : the id of the "object" to query
        
        In the table alert, a "id" is stored in the externalid field. This "id" 
is related to another table, depending on the type of the alert.
        When type=issue, the id is related to a subscriptionid and this sub 
returns the name of the biblio.
        When type=virtual, the id is related to a virtual shelf and this sub 
returns the name of the sub
=cut
sub findrelatedto {
        my ($type,$externalid) = @_;
        my $dbh=C4::Context->dbh;
        my $sth;
        if ($type eq "issue") {
                $sth=$dbh->prepare("select title as result from subscription 
left join biblio on subscription.biblionumber=biblio.biblionumber where 
subscriptionid=?");
        }
        $sth->execute($externalid);
        my ($result) = $sth->fetchrow;
        return $result;
}

END { }       # module clean-up code here (global destructor)