From: djfiander Date: Tue, 16 May 2006 01:44:00 +0000 (+0000) Subject: Initial, incomplete, documentation for ILS::Patron X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=a9ff8b4a3a0bde8304134ab48810f6485d1f4a80;p=working%2FSIPServer.git Initial, incomplete, documentation for ILS::Patron --- diff --git a/ILS/Patron.pod b/ILS/Patron.pod new file mode 100644 index 0000000..72ea5c4 --- /dev/null +++ b/ILS/Patron.pod @@ -0,0 +1,200 @@ +=head1 NAME + +ILS::Patron - Portable Patron status object class for SIP + +=head1 DESCRIPTION + +A C object holds information about a patron that's +used by self service terminals to authenticate and authorize a patron, +and to display information about the patron's borrowing activity. + +=head1 SYNOPSIS + + use ILS; + use ILS::Patron; + + # Look up patron based on patron_id + my $patron = new ILS::Patron $patron_id + + # Basic object access methods + $patron_id = $patron->id; + $str = $patron->name; + $str = $patron->address; + $str = $patron->email_addr; + $str = $patron->home_phone; + $str = $patron->sip_birthdate; + $str = $patron->ptype; + $str = $patron->language; + $str = $patron->password; + $str = $patron->check_password($password); + $str = $patron->currency; + $str = $patron->screen_msg; + $str = $patron->print_line; + + # Check patron permissions + $bool = $patron->charge_ok; + $bool = $patron->renew_ok; + $bool = $patron->recall_ok; + $bool = $patron->hold_ok; + $bool = $patron->card_lost; + $bool = $patron->too_many_charged; + $bool = $patron->too_many_overdue; + $bool = $patron->too_many_renewal; + $bool = $patron->too_many_claim_return; + $bool = $patron->too_many_lost; + $bool = $patron->excessive_fines; + $bool = $patron->excessive_fees; + $bool = $patron->too_many_billed; + + # Patron borrowing activity + $num = $patron->recall_overdue; + $num = $patron->fee_amount; + $bool = $patron->drop_hold($item_id); + @holds = $patron->hold_items($start, $end); + @items = $patron->overdue_items($start, $end); + @items = $patron->charged_items($start, $end); + @items = $patron->fine_items($start, $end); + @items = $patron->recall_items($start, $end); + @items = $patron->unavail_holds($start, $end); + + # Changing a patron's status + $patron->block($card_retained, $blocked_msg); + $patron->enable; + +=head1 INITIALIZATION + +A patron object is created by calling + + $patron = new ILS::Patron $patron_id; + +where C<$patron_id> is the patron's barcode as received from the +self service terminal. If the patron barcode is not registered, +then C should return C. + +=head1 BASIC OBJECT ACCESS METHODS + +The following functions return the corresponding information +about the given patron, or C if the information is +unavailable. + + $patron_id = $patron-Eid; + $str = $patron-Ename; + $str = $patron-Eaddress; + $str = $patron-Eemail_addr; + $str = $patron-Ehome_phone; + + $str = $patron-Escreen_msg; + $str = $patron-Eprint_line; + +If there are outstanding display messages associated with the +patron, then these return the screen message and print line, +respectively, as with the C methods. + +There are a few other object access methods that need a bit more +explication however. + +=head2 C<$str = $patron-Esip_birthdate;> + +Returns the patron's birthday formated according to the SIP +specification: + + YYYYMMDD HHMMSS + +=head2 C<$str = $patron-Eptype;> + +Returns the "patron type" of the patron. This is not used by the +SIP server code, but is passed through to the self service +terminal (using the non-standard protocol field "PC"). Some self +service terminals use the patron type in determining what level +of service to provide (for example, Envisionware computer +management software can be configured to filter internet access +based on patron type). + +=head2 C<$str = $patron-Elanguage;> + +A three-digit string encoding the patron's prefered language. +The full list is defined in the SIP specification, but some of +the important values are: + + 000 Unknown (default) + 001 English + 002 French + 008 Spanish + 011 Canadian French + 016 Arabic + 019 Chinese + 021 North American Spanish + +=head2 C<$bool = $patron-Echeck_password($password);> + +Returns C if C<$patron>'s password is C<$password>. + +=head2 C<$str = $patron-Ecurrency;> + +Returns the three character ISO 4217 currency code for the +patron's preferred currency. + +=head1 CHECK PATRON PERMISSIONS + +Most of the methods associated with Patrons are related to +checking if they're authorized to perform various actions: + + $bool = $patron-Echarge_ok; + $bool = $patron-Erenew_ok; + $bool = $patron-Erecall_ok; + $bool = $patron-Ehold_ok; + $bool = $patron-Ecard_lost; + $bool = $patron-Etoo_many_charged; + $bool = $patron-Etoo_many_overdue; + $bool = $patron-Etoo_many_renewal; + $bool = $patron-Etoo_many_claim_return; + $bool = $patron-Etoo_many_lost; + $bool = $patron-Eexcessive_fines; + $bool = $patron-Eexcessive_fees; + $bool = $patron-Etoo_many_billed; + +=head1 PATRON BORROWING ACTIVITY + + +=head2 C<$num = $patron-Erecall_overdue;> + + +=head2 C<$num = $patron-Efee_amount;> + + +=head2 C<$bool = $patron-Edrop_hold($item_id);> + + +=head2 C<@holds = $patron-Ehold_items($start, $end);> + + +=head2 C<@items = $patron-Eoverdue_items($start, $end);> + + +=head2 C<@items = $patron-Echarged_items($start, $end);> + + +=head2 C<@items = $patron-Efine_items($start, $end);> + + +=head2 C<@items = $patron-Erecall_items($start, $end);> + + +=head2 C<@items = $patron-Eunavail_holds($start, $end);> + + +=head1 CHANGING A PATRON'S STATUS + +=head2 C<$status = $ils-Eblock($card_retained, $blocked_card_msg);> + +Block the account of the patron identified by C<$patron_id>. If +the self check unit captured the patron's card, then +C<$card_retained> will be C. A message indicating why the +card was retained will be provided by the parameter +C<$blocked_card_msg>. + +This function returns an C object that has been +updated to indicate that the patron's privileges have been +blocked, or C if the patron ID is not valid. + +=head2 C<$patron-Eenable;>