Bric::Biz::Person(3p) User Contributed Perl DocumentationBric::Biz::Person(3p)



NAME
       Bric::Biz::Person - Interface to Bricolage Person Objects

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-06-27 21:27:09 +0200 (Tue, 27 Jun 2006) $

SYNOPSIS
         use Bric::Biz::Person;
         # Constructors.
         my $p = Bric::Biz::Person->new($init);
         my $p = Bric::Biz::Person->lookup({ id => $id });
         my @p = Bric::Biz::Person->list($params);

         # Class Methods.
         my @pids = Bric::Biz::Person->list_ids($params);
         my $methds = Bric::Biz::Person->my_meths;

         # Instance Methods.
         my $id = $p->get_id;
         my $lname = $p->get_lname;
         $p = $p->set_lname($lname);
         my $fname = $p->get_fname;
         $p = $p->set_fname($fname);
         my $mname = $p->get_mname;
         $p = $p->set_mname($mname);
         my $prefix = $p->get_prefix;
         $p = $p->set_prefix($prefix);
         my $suffix = $p->get_suffix;
         $p = $p->set_suffix($suffix);
         my $name = $p->format_name($format);

         $p = $p->activate;
         $p = $p->deactivate;
         $p = $p->is_active;

         my @contacts = $p->get_contacts;
         my $contact = $p->new_contact;
         $p->add_new_contacts(@contacts);
         $p = $p->del_contacts;

         my @gids = $p->get_grp_ids;
         my @groups = $p->get_grps;

         my @oids = $p->get_org_ids;
         my @orgs = $p->get_orgs;

         $p = $p->save;

DESCRIPTION
       This Class provides the basic interface to all people in Bricolage. A
       Bric::Biz::Person object may be thought of as a person who plays any
       kind of role in the application. A person may be a user, a writer, a
       producer, an editor, or act in any number of interactive and non-
       interactive roles. Only those people who are added to the
       Bric::Biz::Person::User subclass, however, may actually interact with
       the application.

       Bric::Biz::Person objects can do little other than be associated with
       organizations or store contact information unless they are associated
       with groups. The interface for managing groups of Bric::Biz::Person
       objects is Bric::Util::Grp::Person. Attributes on persons will be
       associated with Bric::Biz::Person objects by reference to their
       membership in certain groups. The Bric::Util::Grp::Person class
       documents how these groups may be created, associated with other
       objects (e.g., associate members of group "Writers" with
       Bric::Biz::Asset::Business::Story objects), and attributes assigned. If
       a Bric::Biz::Person object is a member of a Bric::Util::Grp::Person
       group that defines attributes for its individual members, those
       attributes can be accessed from the Bric::Biz::Person object.

INTERFACE
   Constructors
       my $p = Bric::Biz::Person->new($init)
           Instantiates a Bric::Biz::Person object. An anonymous hash of
           initial values may be passed. The supported initial value keys are:

           o   prefix

           o   lname

           o   fname

           o   mname

           o   suffix

           The active property will be set to true by default. Call $p->save()
           to save the new object.

           Throws:

           o   Incorrect number of args to Bric::_set().

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: NONE.

       my $p = Bric::Biz::Person->lookup({ id => $id })
           Looks up and instantiates a new Bric::Biz::Person object based on
           the Bric::Biz::Person object ID passed. If $id is not found in the
           database, lookup() returns undef.

           Throws:

           o   Too many Bric::Biz::Person objects found.

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: If $id is found, populates the new Bric::Biz::Person
           object with data from the database before returning it.

           Notes: This method is overridden by the lookup() method of
           Bric::Biz::Person::User. That class does not call
           Bric::Biz::Person's lookup() method.

       my (@people || $person_aref) = Bric::Biz::Person->list($params)
           Returns a list or anonymous array of Bric::Biz::Person objects
           based on the search parameters passed via an anonymous hash. The
           supported lookup keys are:

           id  Person ID. May use "ANY" for a list of possible values.

           prefix
               A name prefix, such as "Mr."  May use "ANY" for a list of
               possible values.

           lname
               Last name or surname. May use "ANY" for a list of possible
               values.

           fname
               First name or given name. May use "ANY" for a list of possible
               values.

           mname
               Middle name or second name. May use "ANY" for a list of
               possible values.

           suffix
               Name suffix, such as "Jr." May use "ANY" for a list of possible
               values.

           grp_id
               The ID of a Bric::Util::Grp object of which person objects may
               be a member.  May use "ANY" for a list of possible values.

           Throws:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: Populates each Bric::Biz::Person object with data
           from the database before returning them all.

           Notes: This method is overridden by the list() method of
           Bric::Biz::Person::User. That class does not call
           Bric::Biz::Person's list() method.

   Destructors
       $p->DESTROY
           Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

   Public Class Methods
       my (@person_ids || $person_ids_aref) =
       Bric::Biz::Person->list_ids($params)
           Returns a list or anonymous array of Bric::Biz::Person object IDs
           based on the search criteria passed via an anonymous hash. The
           supported lookup keys are the same as those for list().

           Throws:

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: NONE.

           Notes: This method is overridden by the list_ids() method of
           Bric::Biz::Person::User. That class does not call
           Bric::Biz::Person's list_ids() method.

       $meths = Bric::Biz::Person->my_meths
       (@meths || $meths_aref) = Bric::Biz::Person->my_meths(TRUE)
       my (@meths || $meths_aref) = Bric::Biz::Person->my_meths(0, TRUE)
           Returns an anonymous hash of introspection data for this object. If
           called with a true argument, it will return an ordered list or
           anonymous array of introspection data. If a second true argument is
           passed instead of a first, then a list or anonymous array of
           introspection data will be returned for properties that uniquely
           identify an object (excluding "id", which is assumed).

           Each hash key is the name of a property or attribute of the object.
           The value for a hash key is another anonymous hash containing the
           following keys:

           name
               The name of the property or attribute. Is the same as the hash
               key when an anonymous hash is returned.

           disp
               The display name of the property or attribute.

           get_meth
               A reference to the method that will retrieve the value of the
               property or attribute.

           get_args
               An anonymous array of arguments to pass to a call to get_meth
               in order to retrieve the value of the property or attribute.

           set_meth
               A reference to the method that will set the value of the
               property or attribute.

           set_args
               An anonymous array of arguments to pass to a call to set_meth
               in order to set the value of the property or attribute.

           type
               The type of value the property or attribute contains. There are
               only three types:

               short
               date
               blob
           len If the value is a 'short' value, this hash key contains the
               length of the field.

           search
               The property is searchable via the list() and list_ids()
               methods.

           req The property or attribute is required.

           props
               An anonymous hash of properties used to display the property or
               attribute. Possible keys include:

               type
                   The display field type. Possible values are

                   text
                   textarea
                   password
                   hidden
                   radio
                   checkbox
                   select
               length
                   The Length, in letters, to display a text or password
                   field.

               maxlength
                   The maximum length of the property or value - usually
                   defined by the SQL DDL.

           rows
               The number of rows to format in a textarea field.

           cols
               The number of columns to format in a textarea field.

           vals
               An anonymous hash of key/value pairs reprsenting the values and
               display names to use in a select list.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

   Public Instance Methods
       my $id = $p->get_id
           Returns the ID of the Bric::Biz::Person object.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: READ access for field 'id' required.

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: If the Bric::Biz::Person object has been instantiated via
           the new() constructor and has not yet been "save"d, the object will
           not yet have an ID, so this method call will return undef.

       my $prefix = $p->get_prefix
           Returns the name prefix for the Bric::Biz::Person object.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: READ access for field 'prefix' required.

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       $self = $p->set_prefix($prefix)
           Sets the prefix (e.g., 'Mr.', 'Ms.', 'Sr.', etc.) of the
           Bric::Biz::Person object.  Returns $self on success and undef on
           failure.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: WRITE access for field 'prefix' required.

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       my $fname = $p->get_fname
           Returns the first name for the Bric::Biz::Person object.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: READ access for field 'fname' required.

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       $self = $p->set_fname($fname)
           Sets the first name of the Bric::Biz::Person object. Returns $self
           on success and undef on failure

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: WRITE access for field 'fname' required.

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       my $mname = $p->get_mname
           Returns the middle name for the Bric::Biz::Person object.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: READ access for field 'mname' required.

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       $self = $p->set_mname($mname)
           Sets the middle name of the Bric::Biz::Person object. Returns $self
           on success and undef on failure.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: WRITE access for field 'mname' required.

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       my $lname =  $p->get_lname
           Returns the last name for the Bric::Biz::Person object.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: READ access for field 'lname' required.

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       $self = $p->set_lname($lname)
           Sets the last name of the Bric::Biz::Person object. Returns $self
           on success and undef on failure.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: WRITE access for field 'lname' required.

           o   No AUTOLOAD method.

           Side Effects: NONE.

           Notes: NONE.

       my $suffix = $p->get_suffix
           Returns the name suffix (e.g., 'Jr.,' 'Ph.D., etc.) for the
           Bric::Biz::Person object.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: READ access for field 'suffix' required.

           o   No AUTOLOAD method.

           Side Effects: NONE.

       $self = $p->set_suffix($suffix)
           Sets the suffix property of the Bric::Biz::Person object. Returns
           $self on success and undef on failure.

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

           o   Access denied: WRITE access for field 'suffix' required.

           o   No AUTOLOAD method.

           Notes: NONE.

           Side Effects: NONE.

       $self = $p->activate
           Activates the Bric::Biz::Person object. Call $p->save to make the
           change persistent. Bric::Biz::Person objects instantiated by new()
           are active by default.

           Throws:

           o   Incorrect number of args to Bric::_set().

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: NONE.

       $self = $p->deactivate
           Deactivates (deletes) the Bric::Biz::Person object. Call $p->save
           to make the change persistent.

           Throws:

           o   Incorrect number of args to Bric::_set().

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: NONE.

       $self = $p->is_active
           Returns $self if the Bric::Biz::Person object is active, and undef
           if it is not.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           Side Effects: NONE.

           Notes: NONE.

       my $name = $p->format_name($format)
           Uses the formatting string passed in $format to format the person's
           name. The formats are roughly based on the ideas behind sprintf
           formatting or strftime formatting. Each format is denoted by a
           percent sign (%) and a single letter.  The letter represents the
           data that will be filled in to the string. Any non-alphanumeric
           characters placed between the % and the conversion character will
           be included in the string only if the data represented by the
           conversion character exists.

           For example, if I wanted to get a full name, I would specify a
           format string like so:

             my $format = "%f% m% l";

           In which case, if the person object had a first name "William" and
           a last name "Clinton", but no middle name, the method call

             $p->format_name($format);

           would yield "William Clinton", appropriately omitting the middle
           name and the space preceding it. But if the Bric::Biz::Person
           object also had the middle name "Erin", the same method call would
           yeild "William Jefferson Clinton". Similarly, you can add a comma
           where you need one, but only if you need one. For example, if same
           person object had a prefix of "Mr." and a suffix of "MA", this
           method call:

             $p->format_name("%p% f% M% l%, s");

           would yield "Mr. William J. Clinton, MA", but if there is no suffix
           it yeilds "Mr. William J. Clinton". Here are the supported formats:

             %l Last Name
             %f First Name
             %m Middle Name
             %p Prefix
             %s Suffix
             %L Last Name Initial with Period
             %F First Name Initial with Period
             %M Middle Name Initial with Period
             %T Last Name Initial
             %S First Name Initial
             %I Middle Name Initial

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           Side Effects: NONE.

           Notes: The default format is determined by the "Name Format"
           preference.

       my $name = $p->get_name($format)
           This method is an alias for format_name().

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           Side Effects: NONE.

           Notes: The default format is determined by the "Name Format"
           preference.

       my (@contacts || $contacts_aref) = $p->get_contacts
       my (@contacts || $contacts_aref = $p->get_contacts(@contact_ids)
             foreach my $contact ($p->get_contacts) {
                 print "Name:      ", $contact->get_name, "\n";
                 print "Desc:      ", $contact->get_description, "\n";
                 print "Value:     ", $contact->get_value, "\n";
                 $contact->set_value($value);
             }
             $p->save;

           Returns a list or anonymous array of Bric::Biz::Contact objects. If
           Contact IDs are passed, it will return only those contacts. Any
           changes to individual Bric::Biz::Contact objects will only persist
           after $p->save has been called.

           Bric::Biz::Contact objects each represent a method by which the
           person represented by the Bric::Biz::Person object can be contacted
           (e.g., email, pager, office phone, mobile phone, Instant Messenger,
           etc.). See Bric::Biz::Contact for information on its interface.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           o   Incorrect number of args to Bric::_set().

           o   Bric::set() - Problems setting fields.

           Side Effects: Uses Bric::Util::Coll::Contact internally.

           Notes: NONE.

       my $contact = $p->add_contacts(@contacts)
             $p->add_contacts(@contacts);
             $p->save;

           Adds a list of contacts to the contacts associated with this Person
           Object

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           Side Effects: Uses Bric::Util::Coll::Contact internally.

           Notes: NONE.

       my $contact = $p->new_contact($contact_type_id)
       my $contact = $p->new_contact($contact_type_id, $value)
             $p->new_contact($email_contact_type, $email_address);
             $p->save;

           Returns a new Bric::Biz::Contact object associated with the
           Bric::Biz::Person object.  A list of contact type IDs can be
           retrieved from Bric::Biz::Contact->list_types().  If $value is
           passed, it will be saved to the contact object before returning the
           object. Be sure to call $p->save to save this new contact. See
           Bric::Biz::Contact for information on its interface.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           o   Incorrect number of args to Bric::_set().

           o   Bric::set() - Problems setting fields.

           Side Effects: Uses Bric::Util::Coll::Contact internally.

           Notes: NONE.

       $self = $p->del_contacts
       $self = $p->del_contacts(@contacts)
       $self = $p->del_contacts(@contact_ids)
             $p->del_contacts; # Delete all contacts.
             $p->save;         # Make the deletions persistent.

           Deletes the Bric::Biz::Contact objects associated with the
           Bric::Biz::Person object.  If Bric::Biz::Contact objects or their
           IDs are passed, only those contacts will be deleted. If no values
           are passed, all Bric::Biz::Contact objects associated with the
           Bric::Biz::Person object will be deleted. The deletions will be
           reflected in future calls to get_contacts() for the current
           Bric::Biz::Person instance, but will not persist beyond the current
           instance until $p->save is called.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           o   Incorrect number of args to Bric::_set().

           o   Bric::set() - Problems setting fields.

           Side Effects: Uses Bric::Util::Coll::Contact internally.

           Notes: NONE.

       my (@gids || $gids_aref) = $p->get_grp_ids
           Returns a list or anonymous array of Bric::Util::Grp::Person object
           ids representing the groups of which this Bric::Biz::Person object
           is a member.

           Throws: See Bric::Util::Grp::Person::list().

           Side Effects: NONE.

           Notes: NONE.

           ################################################################################

       my (@groups || $groups_aref) = $p->get_grps
           Returns a list or anonymous array of Bric::Biz::Grp::Person objects
           representing the groups of which this Bric::Biz::Person object is a
           member.

           Use the Bric::Biz::Grp::Person instance method calls add_members()
           and delete_members() to associate and dissociate Bric::Biz::Person
           objects with any given Bric::Biz::Grp::Person object.

           Throws: See Bric::Util::Grp::Person::list().

           Side Effects: Uses Bric::Util::Grp::Person internally.

           Notes: NONE.

       my (@orgs || $orgs_aref) = $p->get_orgs
           Returns a list or anonymous array of Bric::Biz::Org::Person objects
           of which this Bric::Biz::Person object is a member. The first
           Bric::Biz::Org::Person object returned will be the default
           organization created when this Bric::Biz::Person object was
           created. This Bric::Biz::Org::Person object will contain all the
           addresses for the individual Bric::Biz::Person. All the other
           Bric::Biz::Org::Person objects represent organizations (companies,
           etc.) with which this Bric::Biz::Person object is associated. Use
           the get_addr() Bric::Biz::Org::Person method call to retrieve the
           addresses associated with both the Bric::Biz::Org::Person object's
           parent and this Bric::Biz::Person object specifically. See
           Bric::Biz::Org::Person for its API.

           To add a Bric::Biz::Person object to an existing Bric::Biz::Org
           object, simply call the Bric::Biz::Org add_object() method, passing
           it the Bric::Biz::Person object. This method will return the
           resulting Bric::Biz::Org::Person object. See the documentation for
           Bric::Biz::Org and Bric::Biz::Org::Person for more information.

           Throws:

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: Internally calls the Bric::Biz::Org::Person->list()
           class method.

           Notes: NONE.

       my (@oids || $oids_aref) = $p->get_org_ids
           Returns a list or anonymous array of Bric::Biz::Org::Person object
           IDs representing the Bric::Biz::Org::Person objects the
           Bric::Biz::Person object is associated with.  The first
           Bric::Biz::Org::Person ID will be the defalut organization created
           when this Bric::Biz::Person object was created.

           Throws:

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: Internally calls the
           Bric::Biz::Org::Person->list_ids() class method.

           Notes: NONE.

       $self = $p->save
           Saves any changes to the Bric::Biz::Person object, including
           changes to associated contacts (Bric::Biz::Contact objects).
           Returns $self on success and undef on failure.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to execute SQL statement.

           o   Unable to select row.

           o   Incorrect number of args to _set.

           o   Bric::_set() - Problems setting fields.

           Side Effects: Uses Bric::Util::Coll::Contact internally.

           Notes: NONE.

PRIVATE
   Private Class Methods
       NONE.

   Private Instance Methods
       NONE.

   Private Functions
       my $people_aref = &$get_em( $pkg, $search_href )
       my $people_ids_aref = &$get_em( $pkg, $search_href, 1 )
           Function used by lookup() and list() to return a list of
           Bric::Biz::Person objects or, if called with an optional third
           argument, returns a listof Bric::Biz::Person object IDs (used by
           list_ids()).

           Throws:

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects: NONE.

           Notes: NONE.

       my $cont_coll = &$get_cont_coll($self)
           Returns the collection of contacts for this organization. The
           collection is a Bric::Util::Coll::Contact object. See that class
           and its parent, Bric::Util::Coll, for interface details.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           o   Incorrect number of args to Bric::_set().

           o   Bric::set() - Problems setting fields.

           Side Effects: NONE.

           Notes: NONE.

NOTES
       NONE.

AUTHOR
       David Wheeler <david@justatheory.com>

SEE ALSO
       Bric, Bric::Biz::Contact, Bric::Biz::Org, Bric::Biz::Person::User



perl v5.12.2                      2006-06-27             Bric::Biz::Person(3p)
