Attached is a plain o' documentation file (POD) from the current MyLibrary::Resource module. Comments are welcome, and from the synopsis:
# require the necessary module
use MyLibrary::Resource;
# create a new Resource object
my $resource = MyLibrary::Resource->new();
# set attributes of the newly created object
$resource->callno('P 123.456');
$resource->contributor('The Whole Internet Community');
$resource->coverage('Items in the Catalogue date from 600 on');
$resource->creator('Infomotions, Inc.');
$resource->date('2003-11-20');
$resource->fkey('0002345');
$resource->language('en');
$resource->lcd(0);
$resource->name('Alex Catalogue');
$resource->note('This is a list of public domain classic literature');
$resource->proxied(0);
$resource->publisher('Infomotions, Inc.');
$resource->qsearch_prefix('http://infomotions.com/alex?term=');
$resource->qsearch_suffix('sortby=10');
$resource->relation('http://www.promo.net/pg');
$resource->rights('Items in the Catalogue are in the public domain');
$resource->source('Materials of the Catalogue are from all over.');
$resource->url('http://infomotions.com/alex/');
# save the data
$resource->commit;
# get the id of this object
$id = $resource->id();
# create a new object with a specific id
my $resource = MyLibrary::Resource->new (id => $id);
# get selected data from the object
my $name = $resource->name;
my $url = $resource->url;
my $note = $resource->note;
For information on how to download the module from the CVS repository, see:
http://dewey.library.nd.edu/mylibrary/cvs/
--
Eric Lease Morgan
University Libraries of Notre Dame
(574) 631-8604
resource.txt
Description: application/applefile
NAME
MyLibrary::Resource - A class for representing a MyLibrary resource
SYNOPSIS
# require the necessary module
use MyLibrary::Resource;
# create a new Resource object
my $resource = MyLibrary::Resource->new();
# set attributes of the newly created object
$resource->callno('P 123.456');
$resource->contributor('The Whole Internet Community');
$resource->coverage('Items in the Catalogue date from 600 BC to the 1800\'s');
$resource->creator('Infomotions, Inc.');
$resource->date('2003-11-20');
$resource->fkey('0002345');
$resource->language('en');
$resource->lcd(0);
$resource->name('Alex Catalogue');
$resource->note('This is a list of public domain classic literature');
$resource->proxied(0);
$resource->publisher('Infomotions, Inc.');
$resource->qsearch_prefix('http://infomotions.com/alex?term=');
$resource->qsearch_suffix('sortby=10');
$resource->relation('http://www.promo.net/pg');
$resource->rights('Items in the Catalogue are in the public domain');
$resource->source('Materials of the Catalogue were gathered from all over the
Internet.');
$resource->url('http://infomotions.com/alex/');
# save the data
$resource->commit;
# get the id of this object
$id = $resource->id();
# create a new object with a specific id
my $resource = MyLibrary::Resource->new (id => $id);
# get selected data from the object
my $name = $resource->name;
my $url = $resource->url;
my $note = $resource->note;
### to-do ###
# print out all the terms associated with this resource
@terms = $resource->terms();
foreach my $term ( @terms ) {
print $term->property(), " => ", $term->value(), "\n"
}
# print out all the discipline terms
@disciplineTerms = $resource->terms( 'property' => 'discipline' );
foreach my $term ( @disciplineTerms ) {
print $term->value(),"\n"
}
DESCRIPTION
This class is used to represent a MyLibrary resource.
METHODS
new()
This method creates a new resource object. Called with no input, this
method returns a new, empty resource:
# create empty resource
$resource = MyLibrary::Resource->new();
Called with an id, this method returns a resource object containing the
information from the underlying database:
# create a resource from the underlying database
# resource = MyLibrary::Resource->new(id => 123);
The method returns undef if the id is invalid.
name()
This method gets and sets the name of a resource object. The values of
name is intended to be analogous to the Dublin Core name element. To set
the name attribute:
# set the name of a resource
$resource->name('DAIAD Home Page');
To get the value of the name, try:
# get the name
my $name = $resource->name;
note()
Sets and gets the note attribute of a resource object. To set the note's
value, try:
$resource->note('This is a simple note.');
To get the value of the note attribute, do:
my $note = $resource->note;
The sorts of values intended to be stored in note attributes correspond
to the sorts of values assigned to Dublin Core description elements.
url()
The url method is intended to assign a URL to a resource. It works just
like the note method:
# set the url's value
$resource->url('http://dewey.library.nd.edu/');
# get the resources's url value
my $url = $resource->url;
lcd()
This method is used to set and get the "lowest common denominator" (LCD)
value of a resource. LCD resources are resources intended for any
audience, not necessarily discipline-specific audiences. Good candidates
for LCD resources are generic dictionaries, encyclopedias, a library
catalog, or multi-disciplinary bibliographic databases. LCD resoruces
are useful to anybody.
lcd attributes are Boolean in nature; valid values for lcd attributes
are 0 and 1.
To set a resource's lcd attribute:
$resource->lcd(1); # is an LCD resource
$resource->lcd(0); # is not an LCD resource
To get the lcd resource:
$lcd = $resource->lcd;
This method will "croak" if there is an attempt to set the value of lcd
to something other than 0 or 1.
call_no()
Gets and sets the call number attribute (call_no) of a resource. It is
intended to contain the call number of a resource. This method works
exactly like the note method:
# set the call number
$resource->call_no('P 123.45');
# get the call number
my $call_number = $resource->call_no;
fkey()
Gets and sets the fkey value of a resource. Fkey's are "foreign keys"
and intended to be the unique value (database key) of a resource from a
library catalog. The combination of this attribute and the MARION field
of the preferences table should create a URL allowing the user to see
the cataloging record of this resource.
Setting and getting the fkey attribute works like this:
# set the fkey
$resource->fkey('0002345');
# getting the fkey
my $fkey = $resource->fkey;
qsearch_prefix() and qsearch_suffix()
These methods set and get the prefix and suffix values for "Quick
Searches".
Quick Search resources result in an HTML form allowing the end-user to
query a remote Internet database with one input box and one button.
Quick Search resources are reverse-engineered HTML forms supporting the
HTTP GET method. By analyzing the URL's of Internet searches it becomes
apparent that the searches can be divided into three parts: the prefix,
the query, and the suffix. For example, the prefix for a Google search
looks like this:
http://www.google.com/search?hl=en&ie=ISO-8859-1&q=
A query might look like this:
mylibrary
The suffix might look like this:
&btnG=Google+Search
By concatonating these three part together a URL is formed. Once formed
a Web browser (user agent in HTTP parlance) can be redirected to the
newly formed URL and the search results can be displayed.
The qsearch_prefix() and qsearch_suffix() methods are used set and get
the prefixes and suffixes for Quick Searches, and they work just like
the other methods:
# set the prefix and suffix
$resource->qsearch_prefix('http://www.google.com/search?hl=en&ie=ISO-8859-1&q=');
$resource->qsearch_suffix('&btnG=Google+Search');
# create a Quick Search URL by getting the prefixes and suffixes of a resource
my $query = 'mylibrary';
my $quick_search = $resource->qsearch_prefix . $query .
$resource->qsearch_suffix;
date()
Use this method to set and get the date attribute of a resource. This
value is intended to correspond to the the Dublin Core date element and
is used in the system as a date stamp representing when this resource
was last edited thus facilitating a "What's new?" functionality. Date
values are intended to be in a YYYY-MM-DD format.
Setting and getting date attributes works like this:
# set the date
$resource->date('2003-10-28');
# get the date
my $date = $resource->date;
id()
Use this method to get the ID (database key) of a resource. Once
committed, a resource will have a database key, and you can read the
value of this key with this method:
# get the ID of a resource
my $id = $resource->id;
It is not possible to set the value of the id attribute.
commit()
Use this method to save a resource's attributes to the underlying
database, like this:
# save the resource
$resource->commit;
If the resource already exists in the database (it has an id attribute),
then this method will do an SQL UPDATE. If this is a new resource (no
previously assigned id attribute), the method will do an SQL INSERT.
delete()
This method deletes a resource from the underlying database like this:
# delete this resource
$resource->delete;
Once called this method will do an SQL DELETE operation for the given
resource denoted by its id attribute.
get_resources()
This method returns an array of resource objects, specifically, an array
of all the resources in the underlying database. Once called, the
programmer is intended to sort, filter, and process the items in the
array as they see fit. This method takes no input:
# get all the resources
my @all_resources = MyLibrary::Resource->get_resources;
# process each resource
foreach my $r (@all_resources) {
# check for resources from edu domains
if ($r->url =~ /edu/) {
# print them
print $r->name . "\n"
}
}
proxied()
Gets and sets the value of the proxied attribute of a resource:
# set the value of proxied
$resource->proxied(0); # not proxied
$resource->proxied(1); # is proxied
# get the proxied attribute
my $proxied = $resource->proxied;
If a particular resource is licensed, then user agents (Web browsers)
usually need to go through a proxy server before accessing the
resources. This attribute denotes whether or not a resource needs to be
proxied. If true (1), then the resource's URL is intended to be prefixed
with value of the proxy_prefix field in the preferences table. If false
(0), then the URL is intended to stand on its own.
This method will "croak" if the value passed to it is not 1 or 0.
creator()
Use this method to set and get the creator of a resource. The creator
attribute is intended to correspond to the Dublin Core creator element.
The method works just like the note method:
# set the creator value
$resource->creator('University Libraries of Notre Dame');
# get the creator
my $creator = $resource->creator;
publisher()
Use this method to set and get the publisher of a resource. The
publisher attribute is intended to correspond to the Dublin Core
publisher element. The method works just like the note method:
# set the publisher value
$resource->publisher('O\'Reilly and Associates');
# get the publisher
my $publisher = $resource->publisher;
contributor()
Use this method to set and get the contributor of a resource. The
contributor attribute is intended to correspond to the Dublin Core
contributor element. The method works just like the note method:
# set the contributor value
$resource->contributor('The Whole Internet');
# get the contributor
my $contributor = $resource->contributor;
coverage()
Use this method to set and get the coverage of a resource. The coverage
attribute is intended to correspond to the Dublin Core coverage element.
The method works just like the note method:
# set the coverage value
$resource->coverage('Items in the Catalogue date from 600 BC to the 1800\'s.');
# get the coverage
my $coverage = $resource->coverage;
rights()
Use this method to set and get the rights of a resource. The rights
attribute is intended to correspond to the Dublin Core rights element.
The method works just like the note method:
# set the rights value
$resource->rights('This item is in the public domain.');
# get the rights
my $rights = $resource->rights;
language()
Use this method to set and get the language of a resource. The language
attribute is intended to correspond to the Dublin Core language element.
The method works just like the note method:
# set the language value
$resource->language('eng');
# get the language
my $language = $resource->language;
source()
Use this method to set and get the source of a resource. The source
attribute is intended to correspond to the Dublin Core source element.
The method works just like the note method:
# set the source value
$resource->source('This items originated at Virginia Tech.');
# get the source
my $source = $resource->source;
relation()
Use this method to set and get the relation of a resource. The relation
attribute is intended to correspond to the Dublin Core relation element.
The method works just like the note method:
# set the relation value
$resource->relation('http://www.promo.net/pg/');
# get the relation
my $relation = $resource->relation;
SEE ALSO
For more information, see the MyLibrary home page:
http://dewey.library.nd.edu/mylibrary/.
TODO
At the very least, two things need to be done. First, there needs to be
better error checking and graceful returns when errors are encountered.
Second, there needs to be ways to get and set relationships between
resources and controlled vocabuarly terms through the underlying
database's terms table.
HISTORY
First public release, October 28, 2003.
BUGS
In those famous last words, "None."
AUTHORS
Eric Lease Morgan <[EMAIL PROTECTED]>
