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:

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

Throws:

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:

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:

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:

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:

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:

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:

Side Effects: NONE.

Notes: NONE.

my $fname = $p->get_fname

Returns the first name for the Bric::Biz::Person object.

Throws:

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:

Side Effects: NONE.

Notes: NONE.

my $mname = $p->get_mname

Returns the middle name for the Bric::Biz::Person object.

Throws:

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:

Side Effects: NONE.

Notes: NONE.

my $lname = $p->get_lname

Returns the last name for the Bric::Biz::Person object.

Throws:

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:

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:

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:

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:

Side Effects: NONE.

Notes: NONE.

$self = $p->deactivate

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

Throws:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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