NAME
MyLibrary::Patron
SYNOPSIS
# require the necessary module
use MyLibrary::Patron;
# create an undefined Patron object
my $patron = MyLibrary::Patron->new();
# get patron id
my $patron_id = $patron->patron_id();
# set the various attributes of a Patron object
$patron->patron_firstname('Robert');
$patron->patron_surname('Fox');
$patron->patron_image('/path/to/image.jpg');
$patron->patron_url('http://homesite/for/patron');
$patron->patron_username('username');
$patron->patron_organization('University of Notre Dame');
$patron->patron_address_1('address info');
$patron->patron_can_contact(1);
$patron->patron_password('#$@$^&*');
$patron->patron_total_visits(23);
$patron->patron_last_visit('2005-15-08');
$patron->patron_remember_me(1);
$patron->patron_email('yourname@nd.edu');
$patron->patron_stylesheet_id(25);
# commit a Patron to the database
$patron->commit();
# manipulate patron to resource relations
my @patron_resources = $patron->patron_resources(new => [@resource_ids]);
$patron->patron_resources(del => [@resource_ids]);
my @patron_resources = $patron->patron_resources(sort => 'name');
# create, delete and retrieve associated personal links
$patron->add_link(link_name => 'CNN', link_url => 'http://mysite.com');
my $num_deleted = $patron->delete_link(link_id => $link_id);
my @patron_links = $patron->get_links();
# get or set personal link attributes
my $link_id = $patron_links[0]->link_id();
$patron_links[0]->link_name('CNN2');
my $link_name = $patron_links[0]->link_name();
my $link_url = $patron_links[0]->link_url();
# resource usage counts
MyLibrary::Patron->resource_usage(action => 'increment', patron => $patron_id, resource => $resource_id);
my $usage_count = MyLibrary::Patron->resource_usage(action => 'resource_usage_count', patron => $patron_id, resource => $resource_id);
my $resource_usage_count = MyLibrary::Patron->resource_usage(action => 'absolute_usage_count', resource => $resource_id);
my $patron_usage_count = MyLibrary::Patron->resource_usage(action => 'patron_usage_count', resource => $resource_id);
my $patron_resource_count = MyLibrary::Patron->resource_usage(action => 'patron_resource_count', patron => $patron_id);
# manipulate patron -> term relations
my @patron_terms = $patron->patron_terms();
$patron->patron_terms(new => [@term_ids]);
$patron->patron_terms(del => [@term_ids]);
my @patron_terms = $patron->patron_terms(sort => 'name');
# get a list of Patron objects
my @patrons = MyLibrary::Patron->get_patrons();
# delete a Patron object from the database
$patron->delete();DESCRIPTION
Use this module to get and set patron information to a MyLibrary database as well as retrieve a list of all Patron objects in a MyLibrary instance. This package also contains several methods which can be used to retrieve related information about a given patron such as which resources they have selected as well as their customized interface.
METHODS
new()
This class method is the constructor for this package. The method is responsible for initializing all attributes associated with a given Patron object. The method can also be used to create a Patron object using a patron id or name. The patron would thus already need to exist in the database in order for these parameters to have any effect.
patron_id()
This method is used exclusively to retrieve an exising patron's database id, if the patron has been commited to the database. This method may not be used to set a patron's database id.
# get patron id
my $patron_id = $patron->patron_id();This is a required Patron object attribute.
patron_firstname()
This method may be used to either get or set a patron's first name. This is a required attribute, meaning that the object cannot be commited to the database if this attribute is left null.
# set patron_firstname()
$patron->patron_firstname('Robert');
# get patron_firstname()
my $patron_first_name = $patron->patron_firstname();patron_surname()
This method may be used to either get or set a patorn's last name. This is a required attribute, meaning that the object cannot be commited to the database if this attribute is left null.
# set patron_surname()
$patron->patron_surname('Miller');
# get patron_surname()
my $patron_last_name = $patron->patron_surname();patron_image()
This method was added in response to certain metadata standards (namely FOAF), and allows the programmer to add a path within a patron record to an image associated with the patron. For example, the image could be chosen by the patron or a picture of the patron. This is not a required attribute.
# set the patron_image()
$patron->patron_image('/usr/local/bin/me.jpg');
# get the patron_image()
my $patron_image = $patron->patron_image();patron_email()
This method gets or sets a patron's email address. This is not a required attribute.
# set patron's email address
$patron->patron_email('eric');
# get patron's email address
my $email = $patron->patron_email();patron_address_1(), patron_address_2(), patron_address_3(), patron_address_4(), patron_address_5()
These methods should be used to set or get the patron's address information. Typically, this is a street address or building location. This is not a required attribute. The five address fields can contain any information which is appropriate for indicating the patron's full address. These fields are intentionally open ended so that address formats from various nationalities can be stored in these fields. Each field can correspond to a particular line in an address.
# set a patron's address part one
$patron->patron_address_1('2634 Willow Street');
# get a patron's address part one
my $patron_address_one = $patron->patron_address_1();patron_can_contact()
This method should be used to set the can_contact flag. This is a binary attribute, and is not required. However, a devault value of '0' ('Do not contact') will be set if no value is indicated. The input to this method will be sanitized from non-binary content.
# set a patron's can_contact flag
$patron->patron_can_contact(1);
# get a patron's can_contact flag
my $patron_contact_flag = $patron->patron_can_contact();patron_password()
This method can be used to either retrieve or set a patron's password. This attribute will only be used when the system relies upon the 'default' method of authentication (which is to store patron passwords locally as opposed to relying upon an insitutional authentication system). The non-encrypted password chosen and entered by the patron will be encrypted. When the password is retrieved, it will also be in an encrypted form for security purposes. Authentication methods can then be used to perform password verification against this patron attribute. Alpha or numeric digits may be used in a patron's password in any order, however, authentication module methods may place certain requirements on password length and complexity. This method simply encrypts, stores and retrieves patron passwords.
# set the patron's password
my $entered_password = $input->{'password'};
$patron->patron_password($entered_password);
# retrieve the encrypted form of a patron's password
my $patron_password = $patron->patron_password();patron_remember_me()
This method should be used to set the wants_cookie flag, which indicates whether the patron desires to have a "permanent" cookie placed on the current computer they are working on. This will allow the patron to automatically log into their MyLibrary account the next time they use this particular machine. This is a binary attribute, and is not required. However, a devault value of '0' ('Does not want permanent cookie') will be set if no value is indicated. The input to this method will be sanitized from non-binary content.
# set a patron's wants_cookie flag
$patron->patron_remember_me(1);
# get a patron's wants_cookie flag
my $patron_wants_cookie_flag = $patron->patron_remember_me();patron_username()
This method should be used to either set or get a patron's system username. The ultimate source of the username content will either come from the patron themselves or from an external authority (such as an LDAP database). This is the attribute the patron uses to identify themselves to the MyLibrary system. This is a required attribute.
# set the patron's username
$patron->patron_username('johnsmith');
# get a patron's username
my $patron_username = $patron->patron_username();patron_organization()
Use this method as an accessor to the parent organization for the patron. This method will perform the standard set and get operations on this attribute. The organization should correspond to the parent institution within which the patron resides, or could also correspond to sub organizations within the parent institution.
# set the patron's organization
$patron->patron_organization('University of Notre Dame');
# get a patron's organization name
my $patron_organization = $patron->patron_organization();patron_last_visit()
This method can be used to get or set the date of the last time the patron visited the MyLibrary system. The input to this method will be sanitized and if an inappropriate date is input, the method will simply not execute. This is not a required attribute.
# set the date of the last visit
$patron->patron_last_visit('2003-10-05');
# get the date of the last visit
my $patron_last_visit = $patron->patron_last_visit();patron_total_visits()
This method can be used to either retrieve the total number of visits or increment the total visit count by the amount indicated. The amount indicated must be a positive integer. However, this is not a required attribute. Any other parameter input for this method will simply be ignored.
# increment the number of total visits by a certain number
$patron->patron_total_visits(increment => 6);
# retrieve the number of total visits
my $patron_total_visits = $patron->patron_total_visits(); patron_stylesheet_id()
Patrons may indicate a preference for a certain style of their interface. This will organize certain interface attributes such as coordinating colors, graphical options and positioning of interface elements. The stylesheets supplied by MyLibrary administrators will provide the patron with a choice of style for their page. This method must be used to either retrieve or set the stylesheet id with which the patron will be associated. The input to this method must be an integer. This is a required attribute. If no stylesheet id is provided, a default stylesheet will be assigned when the patron initially creates their page. However, the patron can choose another stylesheet at any time.
# associate a stylesheet with a patron
$patron->patron_stylesheet_id(16);
# retrieve the stylesheet associated with this patron
my $patron_stylesheet_id = $patron->patron_stylesheet_id();commit()
This method will simply commit the current Patron object to the database and update any attribute information that has changed for an existing patron. Database integrity checks will be performed upon commit.
# commit the Patron object to the database
$patron->commit();patron_resources()
This object method can be used to create or delete relations between patron objects and resources objects in the underlying database. It can also be used to obtain a list of resource ids associated with a particular patron. The method always returns the current list of resource ids associated with a patron object regardless of the parameters passed to it. If the sort parameter is passed, the list of resource ids returned will be sorted. Currently, sorting is only available by resource name ('name').
Null will be returned if no resources are associated with the patron object. The method will also check to make sure that resources exist that are to be added or deleted. If resource ids are passed to this method which do not correspond to an existing resource object, they will be ignored.
The resources associated with the patron object are, in effect, "owned" by the patron. In other words, these resources have been hand picked for the patron or by the patron in order to form a specialized list somehow associated with the patron. For example, resources may be in the subject area in which the patron is interested, or a list of a certain type of resource that the patron regularly uses. Also, a default list of resources may be created for the patron and this method can be used to make that association.
# simply return a list of associated resource ids
my @patron_resources = $patron->patron_resources();
# retrieve a sorted list
my @sorted_resource_list = $patron->patron_resources(sort => 'name');
# add a list of resources to a patron
$patron->patron_resources(new => [@resource_ids]);
# delete a list of resources from a patron
$patron->patron_resources(del => [@resource_ids]);resource_usage()
This is a class method that can be used to retrieve usage counts based on a number of criteria or increment usage counts for a particular patron and resource. Regarding statistical usage retrieval, counts can be generated according to number of uses by a single patron for a single resource, a group of resources, or statistical tidbits like how many patrons have used a particular resource. The output is entirely dependent upon the type and combination of parameters passed to the method.
Examples for each combination of parameters and output follow.
# simply increment the usage value for a patron and particular resource
MyLibrary::Patron->resource_usage(action => 'increment', patron => $patron_id, resource => $resource_id);
# retrieve the resource usage count for a patron
my $usage_count = MyLibrary::Patron->resource_usage(action => 'resource_usage_count', patron => $patron_id, resource => $resource_id);
# determine an absolute usage count for a patricular resource
my $resource_usage_count = MyLibrary::Patron->resource_usage(action => 'absolute_usage_count', resource => $resource_id);
# determine how many patrons have used a particular resource at least once
my $patron_usage_count = MyLibrary::Patron->resource_usage(action => 'patron_usage_count', resource => $resource_id);
# retrieve a count of resources a particular patron has used
my $patron_resource_count = MyLibrary::Patron->resource_usage(action => 'patron_resource_count', patron => $patron_id);patron_terms()
This object method should be used to manipulate relations between patron and term objects. The output is always the current list of term ids associated with the patron or null. The output list can be sorted by term name. Term object relations can be created or deleted using this method.
# get an unordered list of term ids
my @patron_terms = $patron->patron_terms();
# get a name sorted list of term ids
my @patron_terms = $patron->patron_terms(sort => 'name');
# add term assciations
$patron->patron_terms(new => [@term_ids]);
# delete term associations
$patron->patron_terms(del => [@term_ids]);delete()
This method is used to delete a Patron object from the database. This is an irreversible process.
# delete patron from database
$patron->delete();get_patrons()
This is a class method that will allow the programmer to retrieve all of the patron objects which currently exist in a MyLibrary instance. These are full class objects and any object methods can be used on the objects retrieved using this method. The method will return an array of Patron objects.
# get all patron objects
my @patrons = MyLibrary::Patron->get_patrons();AUTHORS
Robert Fox <rfox2@nd.edu> Eric Lease Morgan <emorgan@nd.edu>