From a9ff8b4a3a0bde8304134ab48810f6485d1f4a80 Mon Sep 17 00:00:00 2001 From: djfiander <djfiander> Date: Tue, 16 May 2006 01:44:00 +0000 Subject: [PATCH] Initial, incomplete, documentation for ILS::Patron --- ILS/Patron.pod | 200 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 ILS/Patron.pod 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<ILS::Patron> 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<new> should return C<undef>. + +=head1 BASIC OBJECT ACCESS METHODS + +The following functions return the corresponding information +about the given patron, or C<undef> if the information is +unavailable. + + $patron_id = $patron-E<gt>id; + $str = $patron-E<gt>name; + $str = $patron-E<gt>address; + $str = $patron-E<gt>email_addr; + $str = $patron-E<gt>home_phone; + + $str = $patron-E<gt>screen_msg; + $str = $patron-E<gt>print_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<ILS> methods. + +There are a few other object access methods that need a bit more +explication however. + +=head2 C<$str = $patron-E<gt>sip_birthdate;> + +Returns the patron's birthday formated according to the SIP +specification: + + YYYYMMDD HHMMSS + +=head2 C<$str = $patron-E<gt>ptype;> + +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-E<gt>language;> + +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-E<gt>check_password($password);> + +Returns C<true> if C<$patron>'s password is C<$password>. + +=head2 C<$str = $patron-E<gt>currency;> + +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-E<gt>charge_ok; + $bool = $patron-E<gt>renew_ok; + $bool = $patron-E<gt>recall_ok; + $bool = $patron-E<gt>hold_ok; + $bool = $patron-E<gt>card_lost; + $bool = $patron-E<gt>too_many_charged; + $bool = $patron-E<gt>too_many_overdue; + $bool = $patron-E<gt>too_many_renewal; + $bool = $patron-E<gt>too_many_claim_return; + $bool = $patron-E<gt>too_many_lost; + $bool = $patron-E<gt>excessive_fines; + $bool = $patron-E<gt>excessive_fees; + $bool = $patron-E<gt>too_many_billed; + +=head1 PATRON BORROWING ACTIVITY + + +=head2 C<$num = $patron-E<gt>recall_overdue;> + + +=head2 C<$num = $patron-E<gt>fee_amount;> + + +=head2 C<$bool = $patron-E<gt>drop_hold($item_id);> + + +=head2 C<@holds = $patron-E<gt>hold_items($start, $end);> + + +=head2 C<@items = $patron-E<gt>overdue_items($start, $end);> + + +=head2 C<@items = $patron-E<gt>charged_items($start, $end);> + + +=head2 C<@items = $patron-E<gt>fine_items($start, $end);> + + +=head2 C<@items = $patron-E<gt>recall_items($start, $end);> + + +=head2 C<@items = $patron-E<gt>unavail_holds($start, $end);> + + +=head1 CHANGING A PATRON'S STATUS + +=head2 C<$status = $ils-E<gt>block($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<true>. A message indicating why the +card was retained will be provided by the parameter +C<$blocked_card_msg>. + +This function returns an C<ILS::Patron> object that has been +updated to indicate that the patron's privileges have been +blocked, or C<undef> if the patron ID is not valid. + +=head2 C<$patron-E<gt>enable;> -- 2.11.0