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

$LastChangedRevision$

$LastChangedDate: 2004-08-12 17:13:34 -0700 (Thu, 12 Aug 2004) $

  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;

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.

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 CW$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. Looks up and instantiates a new Bric::Biz::Person object based on the Bric::Biz::Person object ID passed. If CW$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 CW$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. 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:

*

prefix

*

lname

*

fname

*

mname

*

suffix

*

grp_id 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.

$p->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY. Throws: NONE. Side Effects: NONE. Notes: NONE.

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

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 CWid, 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.

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 CWsaved, the object will not yet have an ID, so this method call will return undef. 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. Sets the prefix (e.g., 'Mr.', 'Ms.', 'Sr.', etc.) of the Bric::Biz::Person object. Returns CW$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. 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. Sets the first name of the Bric::Biz::Person object. Returns CW$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. 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. Sets the middle name of the Bric::Biz::Person object. Returns CW$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. 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. Sets the last name of the Bric::Biz::Person object. Returns CW$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. 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. Sets the suffix property of the Bric::Biz::Person object. Returns CW$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. Activates the Bric::Biz::Person object. Call CW$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. Deactivates (deletes) the Bric::Biz::Person object. Call CW$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. Returns CW$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. Uses the formatting string passed in CW$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. 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.

  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 CW$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.

  $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.

  $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 CW$value is passed, it will be saved to the contact object before returning the object. Be sure to call CW$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.

  $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 CW$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. Returns a list or anonymous array of Bric::Biz::Group::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. ################################################################################ Returns a list or anonymous array of Bric::Biz::Group::Person objects representing the groups of which this Bric::Biz::Person object is a member. Use the Bric::Biz::Group::Person instance method calls add_members() and delete_members() to associate and dissociate Bric::Biz::Person objects with any given Bric::Biz::Group::Person object. Throws: See Bric::Util::Grp::Person::list(). Side Effects: Uses Bric::Util::Grp::Person internally. Notes: NONE. 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. 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. Saves any changes to the Bric::Biz::Person object, including changes to associated contacts (Bric::Biz::Contact objects). Returns CW$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.

NONE.

NONE.

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. 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.

NONE.

David Wheeler <david@wheeler.net>

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