koha-dev.rot13.org Git - koha_ffzg/blob - C4/Members/Messaging.pm

   1 package C4::Members::Messaging;
   2
   3 # Copyright (C) 2008 LibLime
   4 #
   5 # This file is part of Koha.
   6 #
   7 # Koha is free software; you can redistribute it and/or modify it under the
   8 # terms of the GNU General Public License as published by the Free Software
   9 # Foundation; either version 2 of the License, or (at your option) any later
  10 # version.
  11 #
  12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  14 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License along with
  17 # Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
  18 # Suite 330, Boston, MA  02111-1307 USA
  19
  20 use strict;
  21 use warnings;
  22 use C4::Context;
  23
  24 use vars qw($VERSION);
  25
  26 BEGIN {
  27     # set the version for version checking
  28     $VERSION = 3.00;
  29 }
  30
  31 =head1 NAME
  32
  33 C4::Members::Messaging - manage patron messaging preferences
  34
  35 =head1 SYNOPSIS
  36
  37   use C4::Members::Messaging
  38
  39 =head1 DESCRIPTION
  40
  41 This module lets you modify a patron's messaging preferences.
  42
  43 =head1 FUNCTIONS
  44
  45 =head2 GetMessagingPreferences
  46
  47   my $preferences = C4::Members::Messaging::GetMessagingPreferences( { borrowernumber => $borrower->{'borrowernumber'},
  48                                                                        message_name   => 'DUE' } );
  49
  50 returns: a hashref of messaging preferences for this borrower for a particlar message_name
  51
  52 =cut
  53
  54 sub GetMessagingPreferences {
  55     my $params = shift;
  56
  57     foreach my $required ( qw( borrowernumber message_name ) ) {
  58         if ( ! exists $params->{ $required } ) {
  59             return;
  60         }
  61     }
  62
  63     my $sql = <<'END_SQL';
  64 SELECT borrower_message_preferences.*,
  65        borrower_message_transport_preferences.message_transport_type,
  66        message_attributes.*,
  67        message_transports.*
  68   FROM borrower_message_preferences
  69   LEFT JOIN borrower_message_transport_preferences
  70     ON borrower_message_transport_preferences.borrower_message_preference_id = borrower_message_preferences.borrower_message_preference_id
  71   LEFT JOIN message_attributes
  72     ON message_attributes.message_attribute_id = borrower_message_preferences.message_attribute_id
  73   LEFT JOIN message_transports
  74     ON message_transports.message_attribute_id = message_attributes.message_attribute_id
  75     AND message_transports.message_transport_type = borrower_message_transport_preferences.message_transport_type
  76   WHERE borrower_message_preferences.borrowernumber = ?
  77    AND message_attributes.message_name = ?
  78 END_SQL
  79
  80     my @bind_params = ( $params->{'borrowernumber'}, $params->{'message_name'} );
  81
  82     my $sth = C4::Context->dbh->prepare($sql);
  83     $sth->execute(@bind_params);
  84     my $return;
  85     my %transports; # helps build a list of unique message_transport_types
  86     ROW: while ( my $row = $sth->fetchrow_hashref() ) {
  87         next ROW unless $row->{'message_attribute_id'};
  88         # warn( Data::Dumper->Dump( [ $row ], [ 'row' ] ) );
  89         $return->{'days_in_advance'} = $row->{'days_in_advance'} if defined $row->{'days_in_advance'};
  90         $return->{'wants_digest'}    = $row->{'wants_digest'}    if defined $row->{'wants_digest'};
  91                 $return->{'letter_code'}     = $row->{'letter_code'};
  92         $transports{$row->{'message_transport_type'}} = 1;
  93     }
  94     @{$return->{'transports'}} = keys %transports;
  95     return $return;
  96 }
  97
  98 =head2 SetMessagingPreference
  99
 100 This method defines how a user wants to get a certain message delivered.  The
 101 list of valid message types can be delivered can be found in the
 102 C<message_attributes> table, and the list of valid message transports can be
 103 found in the C<message_transport_types> table.
 104
 105   C4::Members::Messaging::SetMessagingPreference( { borrowernumber          => $borrower->{'borrowernumber'}
 106                                                     message_attribute_id    => $message_attribute_id,
 107                                                     message_transport_types => [ qw( email sms ) ],
 108                                                     days_in_advance         => 5
 109                                                     wants_digest            => 1 } )
 110
 111 returns nothing useful.
 112
 113 =cut
 114
 115 sub SetMessagingPreference {
 116     my $params = shift;
 117
 118     foreach my $required ( qw( borrowernumber message_attribute_id message_transport_types ) ) {
 119         if ( ! exists $params->{ $required } ) {
 120             warn "SetMessagingPreference called without required parameter: $required";
 121             return;
 122         }
 123     }
 124     $params->{'days_in_advance'} = undef unless exists ( $params->{'days_in_advance'} );
 125     $params->{'wants_digest'}    = 0     unless exists ( $params->{'wants_digest'} );
 126
 127     my $dbh = C4::Context->dbh();
 128
 129     my $delete_sql = <<'END_SQL';
 130 DELETE FROM borrower_message_preferences
 131   WHERE borrowernumber = ?
 132     AND message_attribute_id = ?
 133 END_SQL
 134     my $sth = $dbh->prepare( $delete_sql );
 135     my $deleted = $sth->execute( $params->{'borrowernumber'}, $params->{'message_attribute_id'} );
 136
 137     if ( $params->{'message_transport_types'} ) {
 138         my $insert_bmp = <<'END_SQL';
 139 INSERT INTO borrower_message_preferences
 140 (borrower_message_preference_id, borrowernumber, message_attribute_id, days_in_advance, wants_digest)
 141 VALUES
 142 (NULL, ?, ?, ?, ?)
 143 END_SQL
 144
 145         $sth = C4::Context->dbh()->prepare($insert_bmp);
 146         my $success = $sth->execute( $params->{'borrowernumber'},
 147                                      $params->{'message_attribute_id'},
 148                                      $params->{'days_in_advance'},
 149                                      $params->{'wants_digest'} );
 150
 151         # my $borrower_message_preference_id = $dbh->last_insert_id();
 152         my $borrower_message_preference_id = $dbh->{'mysql_insertid'};
 153
 154         my $insert_bmtp = <<'END_SQL';
 155 INSERT INTO borrower_message_transport_preferences
 156 (borrower_message_preference_id, message_transport_type)
 157 VALUES
 158 (?, ?)
 159 END_SQL
 160         $sth = C4::Context->dbh()->prepare($insert_bmtp);
 161         foreach my $transport ( @{$params->{'message_transport_types'}}) {
 162             my $success = $sth->execute( $borrower_message_preference_id, $transport );
 163         }
 164     }
 165     return;
 166 }
 167
 168 =head2 GetMessagingOptions
 169
 170   my $messaging_options = C4::Members::Messaging::GetMessagingOptions()
 171
 172 returns a hashref of messaing options available.
 173
 174 =cut
 175
 176 sub GetMessagingOptions {
 177
 178     my $sql = <<'END_SQL';
 179 select message_attributes.message_attribute_id, takes_days, message_name, message_transport_type, is_digest
 180   FROM message_attributes
 181   LEFT JOIN message_transports
 182     ON message_attributes.message_attribute_id = message_transports.message_attribute_id
 183 END_SQL
 184
 185     my $sth = C4::Context->dbh->prepare($sql);
 186     $sth->execute();
 187     my $choices;
 188     while ( my $row = $sth->fetchrow_hashref() ) {
 189         $choices->{ $row->{'message_name'} }->{'message_attribute_id'} = $row->{'message_attribute_id'};
 190         $choices->{ $row->{'message_name'} }->{'message_name'}         = $row->{'message_name'};
 191         $choices->{ $row->{'message_name'} }->{'takes_days'}           = $row->{'takes_days'};
 192         $choices->{ $row->{'message_name'} }->{'has_digest'}           = 1 if $row->{'is_digest'};
 193         $choices->{ $row->{'message_name'} }->{'transport-' . $row->{'message_transport_type'}} = ' ';
 194     }
 195
 196     my @return = values %$choices;
 197     # warn( Data::Dumper->Dump( [ \@return ], [ 'return' ] ) );
 198     return \@return;
 199 }
 200
 201 =head1 TABLES
 202
 203 =head2 message_queue
 204
 205 The actual messages which will be sent via a cron job running
 206 F<misc/cronjobs/process_message_queue.pl>.
 207
 208 =head2 message_attributes
 209
 210 What kinds of messages can be sent?
 211
 212 =head2 message_transport_types
 213
 214 What transports can messages be sent vith?  (email, sms, etc.)
 215
 216 =head2 message_transports
 217
 218 How are message_attributes and message_transport_types correlated?
 219
 220 =head2 borrower_message_preferences
 221
 222 What messages do the borrowers want to receive?
 223
 224 =head2 borrower_message_transport_preferences
 225
 226 What transport should a message be sent with?
 227
 228 =head1 CONFIG
 229
 230 =head2 Adding a New Kind of Message to the System
 231
 232 =over 4
 233
 234 =item 1.
 235
 236 Add a new template to the `letter` table.
 237
 238 =item 2.
 239
 240 Insert a row into the `message_attributes` table.
 241
 242 =item 3.
 243
 244 Insert rows into `message_transports` for each message_transport_type.
 245
 246 =back
 247
 248 =head1 SEE ALSO
 249
 250 L<C4::Letters>
 251
 252 =head1 AUTHOR
 253
 254 Koha Development Team <info@koha.org>
 255
 256 Andrew Moore <andrew.moore@liblime.com>
 257
 258 =cut
 259
 260 1;