ILS/Patron.pod

   1 #
   2 # Copyright (C) 2006-2008  Georgia Public Library Service
   3 #
   4 # Author: David J. Fiander
   5 #
   6 # This program is free software; you can redistribute it and/or
   7 # modify it under the terms of version 2 of the GNU General Public
   8 # License as published by the Free Software Foundation.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public
  16 # License along with this program; if not, write to the Free
  17 # Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  18 # MA 02111-1307 USA
  19
  20 =head1 NAME
  21
  22 ILS::Patron - Portable Patron status object class for SIP
  23
  24 =head1 DESCRIPTION
  25
  26 A C<ILS::Patron> object holds information about a patron that's
  27 used by self service terminals to authenticate and authorize a patron,
  28 and to display information about the patron's borrowing activity.
  29
  30 =head1 SYNOPSIS
  31
  32         use ILS;
  33         use ILS::Patron;
  34
  35         # Look up patron based on patron_id
  36         my $patron = new ILS::Patron $patron_id
  37
  38         # Basic object access methods
  39         $patron_id = $patron->id;
  40         $str = $patron->name;
  41         $str = $patron->address;
  42         $str = $patron->email_addr;
  43         $str = $patron->home_phone;
  44         $str = $patron->sip_birthdate;
  45         $str = $patron->sip_expire;
  46         $str = $patron->ptype;
  47         $str = $patron->language;
  48         $str = $patron->password;
  49         $str = $patron->check_password($password);
  50         $str = $patron->currency;
  51         $str = $patron->screen_msg;
  52         $str = $patron->print_line;
  53
  54         # Check patron permissions
  55         $bool = $patron->charge_ok;
  56         $bool = $patron->renew_ok;
  57         $bool = $patron->recall_ok;
  58         $bool = $patron->hold_ok;
  59         $bool = $patron->card_lost;
  60         $bool = $patron->too_many_charged;
  61         $bool = $patron->too_many_overdue;
  62         $bool = $patron->too_many_renewal;
  63         $bool = $patron->too_many_claim_return;
  64         $bool = $patron->too_many_lost;
  65         $bool = $patron->excessive_fines;
  66         $bool = $patron->excessive_fees;
  67         $bool = $patron->too_many_billed;
  68
  69         # Patron borrowing activity
  70         $num = $patron->recall_overdue;
  71         $num = $patron->fee_amount;
  72         $bool = $patron->drop_hold($item_id);
  73         @holds = $patron->hold_items($start, $end);
  74         @items = $patron->overdue_items($start, $end);
  75         @items = $patron->charged_items($start, $end);
  76         @items = $patron->fine_items($start, $end);
  77         @items = $patron->recall_items($start, $end);
  78         @items = $patron->unavail_holds($start, $end);
  79
  80         # Changing a patron's status
  81         $patron->block($card_retained, $blocked_msg);
  82         $patron->enable;
  83
  84 =head1 INITIALIZATION
  85
  86 A patron object is created by calling
  87
  88         $patron = new ILS::Patron $patron_id;
  89
  90 where C<$patron_id> is the patron's barcode as received from the
  91 self service terminal.  If the patron barcode is not registered,
  92 then C<new> should return C<undef>.
  93
  94 =head1 BASIC OBJECT ACCESS METHODS
  95
  96 The following functions return the corresponding information
  97 about the given patron, or C<undef> if the information is
  98 unavailable.
  99
 100         $patron_id = $patron-E<gt>id;
 101         $str = $patron-E<gt>name;
 102         $str = $patron-E<gt>address;
 103         $str = $patron-E<gt>email_addr;
 104         $str = $patron-E<gt>home_phone;
 105
 106         $str = $patron-E<gt>screen_msg;
 107         $str = $patron-E<gt>print_line;
 108
 109 If there are outstanding display messages associated with the
 110 patron, then these return the screen message and print line,
 111 respectively, as with the C<ILS> methods.
 112
 113 There are a few other object access methods that need a bit more
 114 explication however.
 115
 116 =head2 C<$str = $patron-E<gt>sip_birthdate;>
 117
 118 Returns the patron's birthday formated according to the SIP
 119 specification:
 120
 121         YYYYMMDD    HHMMSS
 122
 123 =head2 C<$str = $patron-E<gt>sip_expire;>
 124
 125 Returns the patron's expiration formated according to the SIP
 126 specification:
 127
 128         YYYYMMDD    HHMMSS
 129
 130 =head2 C<$str = $patron-E<gt>ptype;>
 131
 132 Returns the "patron type" of the patron.  This is not used by the
 133 SIP server code, but is passed through to the self service
 134 terminal (using the non-standard protocol field "PC").  Some self
 135 service terminals use the patron type in determining what level
 136 of service to provide (for example, Envisionware computer
 137 management software can be configured to filter internet access
 138 based on patron type).
 139
 140 =head2 C<$str = $patron-E<gt>language;>
 141
 142 A three-digit string encoding the patron's prefered language.
 143 The full list is defined in the SIP specification, but some of
 144 the important values are:
 145
 146         000 Unknown (default)
 147         001 English
 148         002 French
 149         008 Spanish
 150         011 Canadian French
 151         016 Arabic
 152         019 Chinese
 153         021 North American Spanish
 154
 155 =head2 C<$bool = $patron-E<gt>check_password($password);>
 156
 157 Returns C<true> if C<$patron>'s password is C<$password>.
 158
 159 =head2 C<$str = $patron-E<gt>currency;>
 160
 161 Returns the three character ISO 4217 currency code for the
 162 patron's preferred currency.
 163
 164 =head1 CHECKING PATRON PERMISSIONS
 165
 166 Most of the methods associated with Patrons are related to
 167 checking if they're authorized to perform various actions:
 168
 169         $bool = $patron-E<gt>charge_ok;
 170         $bool = $patron-E<gt>renew_ok;
 171         $bool = $patron-E<gt>recall_ok;
 172         $bool = $patron-E<gt>hold_ok;
 173         $bool = $patron-E<gt>card_lost;
 174         $bool = $patron-E<gt>recall_overdue;
 175         $bool = $patron-E<gt>too_many_charged;
 176         $bool = $patron-E<gt>too_many_overdue;
 177         $bool = $patron-E<gt>too_many_renewal;
 178         $bool = $patron-E<gt>too_many_claim_return;
 179         $bool = $patron-E<gt>too_many_lost;
 180         $bool = $patron-E<gt>excessive_fines;
 181         $bool = $patron-E<gt>excessive_fees;
 182         $bool = $patron-E<gt>too_many_billed;
 183
 184 =head1 LISTS OF ITEMS ASSOCIATED WITH THE USER
 185
 186 The C<$patron> object provides a set of methods to find out
 187 information about various sets that are associated with the
 188 user.  All these methods take two optional parameters: C<$start>
 189 and C<$end>, which define a subset of the list of items to be
 190 returned (C<1> is the first item in the list).  The following
 191 methods all return a reference to a list of C<$item_id>s:
 192
 193         $items = $patron-E<gt>hold_items($start, $end);
 194         $items = $patron-E<gt>overdue_items($start, $end);
 195         $items = $patron-E<gt>charged_items($start, $end);
 196         $items = $patron-E<gt>recall_items($start, $end);
 197         $items = $patron-E<gt>unavail_holds($start, $end);
 198
 199 It is also possible to retrieve an itemized list of the fines
 200 outstanding.  This method returns a reference to an itemized list
 201 of fines:
 202
 203         $fines = $patron-E<gt>fine_items($start, $end);
 204
 205 =head1 PATRON BORROWING ACTIVITY
 206
 207 =head2 C<$num = $patron-E<gt>fee_amount;>
 208
 209 The total amount of fees and fines owed by the patron.
 210
 211 =head2 C<$bool = $patron-E<gt>drop_hold($item_id);>
 212
 213 Drops the hold that C<$patron> has placed on the item
 214 C<$item_id>.  Returns C<false> if the patron did not have a hold
 215 on the item, C<true> otherwise.
 216
 217
 218
 219 =head1 CHANGING A PATRON'S STATUS
 220
 221 =head2 C<$status = $ils-E<gt>block($card_retained, $blocked_card_msg);>
 222
 223 Block the account of the patron identified by C<$patron_id>.  If
 224 the self check unit captured the patron's card, then
 225 C<$card_retained> will be C<true>.  A message indicating why the
 226 card was retained will be provided by the parameter
 227 C<$blocked_card_msg>.
 228
 229 This function returns an C<ILS::Patron> object that has been
 230 updated to indicate that the patron's privileges have been
 231 blocked, or C<undef> if the patron ID is not valid.
 232
 233 =head2 C<$patron-E<gt>enable;>
 234
 235 Reenable the patron after she's been blocked.  This is a test
 236 function and will not normally be called by self-service
 237 terminals in production.