NAME

Bric::Biz::Contact - Interface to Contacts

VERSION

$Revision: 1.8 $

DATE

$Date: 2002/08/30 22:13:38 $

SYNOPSIS

use Bric::Biz::Contact

# Constructors.
my $c = Bric::Biz::Contact->new($init);
my $c = Bric::Biz::Contact->lookup({ id => $id });
my @c = Bric::Biz::Contact->list($params);

# Class Methods.
my @cids = Bric::Biz::Contact->list_ids($params);
my $methods = Bric::Biz::Contact->my_meths;

# Contact Type managment.
my @types = Bric::Biz::Contact->list_types;
my $types_href = Bric::Biz::Contact->href_types;
my @types = Bric::Biz::Contact->list_alertable_types;
my $types_href = Bric::Biz::Contact->href_alertable_types;
my $type_ids_href = Bric::Biz::Contact->href_alertable_type_ids;
my $bool = Bric::Biz::Contact->edit_type($type, $description);
my $bool = Bric::Biz::Contact->deactivate_type($type);

# Instance Methods.
my $id = $c->get_id;
my $type = $c->get_type;
$c = $c->set_type($type);
my $desc = $c->get_description;
my $value = $c->get_value;
$c = $c->set_value($value);

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

$c = $c->save;

DESCRIPTION

This class manages contacts. Currently, contacts are only associated with Bric::Biz::Person objects, but they could conceivabley be associated with other objects, e.g., Bric::Biz::Org.

A contact is a method (other than snail mail) to contact a person. Default contact types include "Primary Email," "Secondary Email," "Office Phone," "Mobile Phone," "AOL Instant Messenger," etc. These types can be modifed and new contact types can be added via this class' class methods. Each individual Bric::Biz::Contact object has an associated type, the types' description, and a value. Each is also associated with another object, so they will often be accessed from that object (see Bric::Biz::Person for an example).

INTERFACE

Constructors

my $c = Bric::Biz::Contact->new()
my $c = Bric::Biz::Contact->new($init)

Instantiates a Bric::Biz::Contact 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 $c->save() to save the new object.

Throws:

Side Effects: NONE.

Notes: NONE.

my $c = Bric::Biz::Contact->lookup({ id => $id })

Looks up and instantiates a new Bric::Biz::Contact object based on the Bric::Biz::Contact 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::Contact object with data from the database before returning it.

Notes: NONE.

my (@contacts || $contact_aref) = Bric::Biz::Contact->list($params)

Returns a list or anonymous array of Bric::Biz::Contact objects based on the search parameters passed via an anonymous hash. The supported lookup keys are:

Throws:

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

Notes: NONE.

my $contacts_href = Bric::Biz::Contact->href($params)

Works the same as list(), with the same arguments, except it returns a hash or hashref of Bric::Biz::Contact objects, where the keys are the contact IDs, and the values are the contact objects.

Throws:

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

Notes: NONE.

Destructors

$p->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Class Methods

my (@c_ids || $c_ids_aref) = Bric::Biz::Contact->list_ids($params)

Returns a list or anonymous array of Bric::Biz::Contact object IDs based on the search parameters passed via an anonymous hash. The supported lookup keys are the same as those for list().

Throws:

Side Effects: NONE.

Notes: NONE.

$meths = Bric::Biz::Person->my_meths
(@meths || $meths_aref) = Bric::Biz::Person->my_meths(TRUE)

Returns an anonymous hash of instrospection data for this object. If called with a true argument, it will return an ordered list or anonymous array of intrspection data. The format for each introspection item introspection is as follows:

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:

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my (@types || $type_aref) = Bric::Biz::Contact->list_types

Returns a list or anonymous array of all the possible types of contacts. Use these types to set the type of a contact via $c->set_type().

Throws:

Side Effects: NONE.

Notes: NONE.

my $type_href = Bric::Biz::Contact->href_types

Returns a hash list or anonymous hash of all the possible types of contacts. The hash keys are the type names, and the hash values are the descriptions.

Throws:

Side Effects: NONE.

Notes: NONE.

my (@types || $type_aref) = Bric::Biz::Contact->list_alertable_types

Returns a list or anonymous array of contact types that are alertable, that is, contacts of these types may be used for sending alerts.

Throws:

Side Effects: NONE.

Notes: NONE.

my $types_aref = Bric::Biz::Contact->href_alertable_types

Returns a hash list or anonymous hash of contact types that are alertable, that is, contacts of these types may be used for sending alerts. The hash keys are the type names and the values are their descriptions.

Throws:

Side Effects: NONE.

Notes: NONE.

my $types_aref = Bric::Biz::Contact->href_alertable_type_ids

Returns a hash list or anonymous hash of contact types that are alertable, that is, contacts of these types may be used for sending alerts. The hash keys are they type names and the values are theiry IDs. Used by Bric::Util::Alert.

Throws:

Side Effects: NONE.

Notes: NONE.

my $success = Bric::Biz::Contact->edit_type($type, $description)

Adds or alters a contact type. If the type exists, it's description will be updated and it will be activated. If it does not exist, it will be created.

Throws:

Side Effects: NONE.

Notes: NONE.

my $success = Bric::Biz::Contact->deactivate_type($type)

Deletes a type. All contacts of this type will be automatically deactivated. To reactivate a type, use edit_type(); all existing contacts of that type will then be available again.

Throws:

Side Effects: NONE.

Notes: NONE.

Public Instance Methods

my $id = $c->get_id

Returns the ID of the Bric::Biz::Contact object.

Throws:

Side Effects: NONE.

Notes: If the Bric::Biz::Contact 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 $type = $c->get_type

Returns the type of the Bric::Biz::Contact object.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $c->set_type($type)

Sets the type type of the contact. The type type must be a valid type as returned by get_types().

Throws:

Side Effects: NONE.

Notes: NONE.

my $description = $c->get_description

Returns the description of the Bric::Biz::Contact object. If the contact has not been looked up from the database or if it's type has changed, description will be undef.

Throws:

Side Effects: NONE.

Notes: NONE.

my $value = $c->get_value

Returns the value of the Bric::Biz::Contact object.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $c->set_value($value)

Sets the value of the Bric::Biz::Contact object. Returns $self on success and undef on failure.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $c->activate

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

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $c->deactivate

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

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $c->is_active

Returns $self if the Bric::Biz::Contact object is active, and undef if it is not.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $p->save

Saves any changes to the Bric::Biz::Contact object, including changes to associated contacts (Bric::Biz::Attribute::Contact::Contact objects) and attributes (Bric::Biz::Attribute::Contact objects). Returns $self on success and undef on failure.

Throws:

Side Effects: Cleans out internal cache of Bric::Biz::Attr::Contact::Contact and Bric::Biz::Attribute::Contact objects to reflect what is in the database.

Notes: NONE.

PRIVATE

Private Class Methods

NONE.

Private Instance Methods

NONE.

Private Functions

my $contacts_aref = &$get_em( $pkg, $search_href )
my $contacts_ids_aref = &$get_em( $pkg, $search_href, 1 )

Function used by lookup() and list() to return a list of Bric::Biz::Contact objects or, if called with an optional third argument, returns a listof Bric::Biz::Contact object IDs (used by list_ids()).

Throws:

Side Effects: NONE.

Notes: NONE.

my (@types || $types_aref) = &$get_types()
my (%types || $types_href) = &$get_types(1)
my (@alertable_types || $alertable_types_aref) = &$get_types(undef, 1)
my (%alertable_types || $alertable_types_href) = &$get_types(1, 1)
my (%alertable_type_ids || $alertable_type_ids_href) = &$get_types(1, 1, 1)

Function used by list_types(), href_types(), list_alertable_types(), href_alertable_types(), and href_alertable_type_ids() to return an anonymous array or anonymous hash of contact types.

The arguments are as follows:

0

If no arguments are passed, a simple list of contact type names is returned.

1

The first arugment requires that a hash list or anonymous hash be returned, where the hash keys are the contact type names and the values are the contact type descriptions.

2

The second argument specifies that the values returned by the the method reflect only those contact types that are alertable.

3

The third argument specifies that the hash values returned by the inclusion of the second argument be the contact type IDs, rather than their descriptions.

Throws:

Side Effects: NONE.

Notes: NONE.

NOTES

NONE.

AUTHOR

David Wheeler <david@wheeler.net>

SEE ALSO

Bric

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 361:

=back doesn't take any parameters, but you said =back 4

Around line 517:

Expected '=item *'

Around line 519:

Expected '=item *'

Around line 521:

Expected '=item *'

Around line 523:

Expected '=item *'

Around line 525:

Expected '=item *'

Around line 527:

Expected '=item *'

Around line 529:

Expected '=item *'

Around line 1304:

=back doesn't take any parameters, but you said =back 4

Around line 1520:

You forgot a '=back' before '=head1'