• Name
• Synopsis
• Description
• Interface
  • Constructors
  • Destructors
  • Public Class Methods
  • Public Instance Methods
• Private
  • Private Class Methods
  • Private Instance Methods
  • Private Functions
• Notes
• Author
• See Also

Name

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

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 saved, 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::Util::Grp::Person objects representing the groups of which this Bric::Biz::Person object is a member.

  Use the Bric::Util::Grp::Person instance method calls add_members() and delete_members() to associate and dissociate Bric::Biz::Person objects with any given Bric::Util::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

See Also

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