Bric::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:

    *   prefix

    *   lname

    *   fname

    *   mname

    *   suffix

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

    Throws:

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

    *   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:

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

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   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:

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   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:

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

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

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

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

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

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

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

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

    *   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:

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

    *   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:

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

    *   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:

    *   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:

    *   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:

    *   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:

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

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

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

    *   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:

    *   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:

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

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

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

    *   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:

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

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

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

    *   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:

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   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:

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   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:

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

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to execute SQL statement.

    *   Unable to select row.

    *   Incorrect number of args to _set.

    *   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:

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   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:

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

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

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

    *   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