Initial pass at documentation for ILS::Item

diff --git a/ILS/Item.pod b/ILS/Item.pod
new file mode 100644 (file)
index 0000000..6420b57
--- /dev/null
+++ b/ILS/Item.pod
@@ -0,0 +1,231 @@
+=head1 NAME
+
+ILS::Item - Portable Item status object class for SIP
+
+=head1 SYNOPSIS
+
+       use ILS;
+       use ILS::Item;
+
+       # Look up item based on item_id
+       my $item = new ILS::Item $item_id;
+
+       # Basic object access methods
+       $item_id = $item->id;
+       $title = $item->title_id;
+       $media_type = $item->sip_media_type;
+       $bool = $item->magnetic;
+       $locn = $item->permanent_location;
+       $locn = $item->current_location;
+       $props = $item->sip_item_props;
+       $owner = $item->owner;
+       $str = $item->sip_circulation_status;
+       $bool = $item->available;
+       @hold_queue = $item->hold_queue;
+       $pos = $item->hold_queue_position($patron_id);
+       $due = $item->due_date;
+       $pickup = $item->hold_pickup_date;
+       $recall = $item->recall_date;
+       $fee = $item->fee;
+       $currency = $item->fee_currency;
+       $type = $item->sip_fee_type;
+       $mark = $item->sip_security_marker;
+       $msg = $item->screen_msg;
+       $msg = $item->print_line;
+
+       # Operations on items
+       $status = $item->status_update($item_props);
+
+=head1 DESCRIPTION
+
+An C<ILS::Item> object holds the information necessary to
+circulate an item in the library's collection.  It does not need
+to be a complete bibliographic description of the item; merely
+basic human-appropriate identifying information is necessary
+(that is, not the barcode, but just a title, and maybe author).
+
+For the most part, C<ILS::Item>s are not operated on directly,
+but are passed to C<ILS> methods as part of a transaction.  That
+is, rather than having an item check itself in:
+
+       $item->checkin;
+
+the code tells the ILS that the item has returned:
+
+       $ils->checkin($item_id);
+
+Similarly, patron's don't check things out (a la,
+C<$patron-E<gt>checkout($item)>), but the ILS checks items out to
+patrons.  This means that the methods that are defined for items
+are, almost exclusively, methods to retrieve information about
+the state of the item.
+
+=over
+
+=item C<$item_id = $item-E<gt>id>
+
+Return the item ID, or barcode, of C<$item>.
+
+=item C<$title = $item-E<gt>title_id>
+
+Return the title, or some other human-relevant description, of
+the item.
+
+=item C<$media_type = $item-E<gt>media_type>
+
+Return the SIP-defined media type of the item.  The specification
+provides the following definitions:
+
+       000 Other
+       001 Book
+       002 Magazine
+       003 Bound journal
+       004 Audio tape
+       005 Video tape
+       006 CD/CDROM
+       007 Diskette
+       008 Book with diskette
+       009 Book with CD
+       010 Book with audio tape
+
+The SIP server does not use the media type code to alter its
+behavior at all; it merely passes it through to the self-service
+terminal.  In particular, it does not set indicators related to
+whether an item is magnetic, or whether it should be
+desensitized, based on this return type.  The
+C<$item-E<gt>magnetic> method will be used for that purpose.
+
+=item C<magnetic>
+
+Is the item some form of magnetic media (eg, a video or a book
+with an accompanying floppy)?  This method will not be called
+unless 
+
+    $ils->supports('magnetic media')
+
+returns C<true>.
+
+If this method is defined, it is assumed to return either C<true>
+or C<false> for every item.  If the magnetic media indication is
+not supported by the ILS, then the SIP server will indicate that
+all items are 'Unknown'.
+
+=item C<$locn = $item-E<gt>permanent_location>
+
+Where does this item normally reside?  The protocol specification
+is not clear on whether this is the item's "home branch", or a
+location code within the branch, merely stating that it is, "The
+location where an item is normally stored after being checked
+in."
+
+=item C<$locn = $item-E<gt>current_location>
+
+According to the protocol, "[T]he current location of the item.
+[A checkin terminal] could set this field to the ... system
+terminal location on a Checkin message."
+
+=item C<$props = $item-E<gt>sip_item_props>
+
+Returns "item properties" associated with the item.  This is an
+(optional) opaque string that is passed between the self-service
+terminals and the ILS.  It can be set by the terminal, and should
+be stored in the ILS if it is.
+
+=item C<$owner = $item-E<gt>owner>
+
+The spec says, "This field might contain the name of the
+institution or library that owns the item."
+
+=item C<$str = $item-E<gt>sip_circulation_status>
+
+Returns a two-character string describing the circulation status
+of the item, as defined in the specification:
+
+       01 Other
+       02 On order
+       03 Available
+       04 Charged
+       05 Charged; not to be recalled until earliest recall date
+       06 In process
+       07 Recalled
+       08 Waiting on hold shelf
+       09 Waiting to be re-shelved
+       10 In transit between library locations
+       11 Claimed returned
+       12 Lost
+       13 Missing
+
+=item C<$bool = $item-E<gt>available>
+
+Is the item available?  That is, not checked out, and not on the
+hold shelf?
+
+=item C<@hold_queue = $item-E<gt>hold_queue>
+
+Returns a list of the C<$patron_id>s of the patrons that have
+outstanding holds on the item.
+
+=item C<$pos = $item-E<gt>hold_queue_position($patron_id)>
+
+Returns the location of C<$patron_id> in the hold queue for the
+item, with '1' indicating the next person to receive the item.  A
+return status of '0' indicates that C<$patron_id> does not have a
+hold on the item.
+
+=item C<$date = $item-E<gt>recall_date>
+=item C<$date = $item-E<gt>hold_pickup_date>
+
+These functions all return the corresponding date as a standard
+SIP-format timestamp:
+
+       YYYYMMDDZZZZHHMMSS
+
+Where the C<'Z'> characters indicate spaces.
+
+=item C<$date = $item-E<gt>due_date>
+
+Returns the date the item is due.  The format for this timestamp
+is not defined by the specification, but it should be something
+simple for a human reader to understand.
+
+=item C<$fee = $item-E<gt>fee>
+
+The amount of the fee associated with borrowing this item.
+
+=item C<$currency = $item-E<gt>fee_currency>
+
+The currency in which the fee type above is denominated.  This
+field is the ISO standard 4217 three-character currency code.  It
+is highly unlikely that many systems will denominate fees in more
+than one currency, however.
+
+=item C<$type = $item-E<gt>sip_fee_type>
+
+The type of fee being charged, as defined by the SIP protocol
+specification:
+
+       01 Other/unknown
+       02 Administrative
+       03 Damage
+       04 Overdue
+       05 Processing
+       06 Rental
+       07 Replacement
+       08 Computer access charge
+       09 Hold fee
+
+=item C<$mark = $item-E<gt>sip_security_marker>
+
+The type of security system with which the item is tagged:
+
+       00 Other
+       01 None
+       02 3M Tattle-tape
+       03 3M Whisper tape
+
+=item C<$msg = $item-E<gt>screen_msg>
+=item C<$msg = $item-E<gt>print_line>
+
+The usual suspects.
+
+=back