NAME

Liz::OCASet::Contact - generic module for Contact objects


SYNOPSIS

 use xxLINK;
 $xxlink = new xxLINK;
 $ocaset = $xxlink->OCASet( 'customers' );
 
 $contact = $ocaset->Contact;
 $contact = $ocaset->Contact( $contactID );

 $firstname = $contact->FirstName;
 $prefix = $contact->Prefix;
 $name = $contact->Name;
 $addressID = $contact->AddressID;
 $contactID = $contact->update;


DESCRIPTION

Provide object oriented access to the Contact object of the Liz::OCASet module family. Usually not accessed directly, but rather through a client module.

The Contact object is uniquely keyed on both the name as well as on the email address. If an email address of the Contact is available, then only one object can exists with that email address (and hence only one name can be available with that email address). If there is no email address associated with the Contact, then the sortname is used as the unique key on which the object can be found. In turn, the sortname is determined by the firstname, prefix and name if not specified explicitely.

This approach allows Contacts with and without email address to co-exist within the same database without interfering with each other.


BASIC METHODS


new

Create a new Contact object from a client module object.

Input Parameters

 1 Liz::SQL object
 2 ID or name to create Contact object with (e.g.'Dijk')
 3 if 2==name: firstname of contact (e.g. 'Wendy')
 4 if 2==name: prefix of contact (e.g. 'van')
 5 if 2==name: name on which to sort the object on
   (default: name,firstname,prefix as lowercase with alpha only)
Output Parameters

 1 instantiated object
Note

It is not intended to call this method directly, but rather indirectly through a client module.

Example

 $xxlink = new xxLINK;
 $ocaset = $xxlink->OCASet( 'customers' );
 $contact = $ocaset->Contact;
 $contact = $ocaset->Contact( 'Dijk','Wendy','van' );
 $contact = $ocaset->Contact( $contactID );


update

Update a Contact object in the database.

Input Parameters

 1 flag: whether to really add with new ID (0=add, 1=do NOT add, just fetch ID)
   (default: add)
Output Parameters

 1 ID with which the object was updated (undef = error)
Example

 $contact->update;


CONTENT METHODS

The following methods allow you to change the fields associated with the Liz::OCASet::Contact object.


Address

Create a Liz::OCASet::Address object, either from existing information or for a new entry. For more documentation, see the Liz::OCASet::Address object itself.

Input Parameters

 1 ID to create Address object with
   (default: addressID associated with object, 0 to indicate new Address object)
Output Parameters

 1 instantiated Liz::OCASet::Address object
Example

 $xxlink = new xxLINK;
 $ocaset = $xxlink->OCASet( 'customers' );
 $contact = $ocaset->Contact;
 $address = $contact->Address;
 :
 $addressID = $address->update;
 $contact->AddressID( $addressID );
 $contact->update;


AddressID

Return or set the AddressID information of the Liz::OCASet::Contact object.

Input Parameters

 1 new value of the AddressID
   (default: no change)
Output Parameters

 1 current/old name value of the AddressID
Example

 $contact->AddressID( $addressID );
 $addressID = $contact->AddressID;


Created

Return the Created information of the Liz::OCASet::Contact object.

Output Parameters

 1 current timestamp of the Created
Example

 $created = $contact->Created;


Data

Return or set the Data information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the Data
   (default: no change)
Output Parameters

 1 current/old name of the Data
Example

 $contact->Data( Scalars2Hash( qw($aap $noot $mies) ) );
 Hash2Scalars( $contact->Data );


Email

Return or set the Email information of the Liz::OCASet::Contact object. When setting the email address, sets the field ERROR if there was an error in the format of the email address.

Input Parameters

 1 new name of the Email
   (default: no change)
Output Parameters

 1 current/old name of the Email
Example

 $address->Email( 'liz@xxLINK.nl' )
 $email = $address->Email;


Fax

Return or set the Fax information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the Fax number
   (default: no change)
Output Parameters

 1 current/old name of the Fax number
Example

 $address->Fax( '+31 20 6001825' );
 $fax = $address->Fax;


FirstName

Return or set the FirstName information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the FirstName
   (default: no change)
Output Parameters

 1 current/old name of the FirstName
Example

 $contact->FirstName( 'Elizabeth' );
 $firstname = $contact->FirstName;


ForeignKey

Return or set the ForeignKey information of the Liz::OCASet::Contact object. A foreign key is nothing else than another descriptor of the object. It is usually used if the Contact database is created from an externally supplied database.

Input Parameters

 1 new name of the ForeignKey
   (default: no change)
Output Parameters

 1 current/old name of the ForeignKey
Example

 $contact->ForeignKey( '009689' );
 $foreignkey = $contact->ForeignKey;


Gender

Return or set the Gender information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the Gender
   (default: no change)
Output Parameters

 1 current/old name of the Gender
Example

 $contact->Gender( 'Mrs.' );
 $gender = $contact->Gender;


IP

Return the IP number from where the object was last edited.

Output Parameters

 1 IP-number where record was last edited
Example

 $ip = $contact->IP;


Name

Return or set the Name information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the Name
   (default: no change)
Output Parameters

 1 current/old name of the Name
Example

 $contact->Name( 'Mattijsen' );
 $name = $contact->Name;


Options

Return or set the Options information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the Options
   (default: no change)
Output Parameters

 1 current/old name of the Options
Example

 $contact->Options( 'ACF' );
 $options = $contact->Options;


OrganizationID

Return or set the OrganizationID information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the OrganizationID
   (default: no change)
Output Parameters

 1 current/old name of the OrganizationID
Example

 $contact->OrganizationID( $organizationID );
 $organizationID = $contact->OrganizationID;


PostalAddressID

Return or set the PostalAddressID information of the Liz::OCASet::Contact object.

Input Parameters

 1 new value of the PostalAddressID
   (default: no change)
Output Parameters

 1 current/old value of the PostalAddressID
Example

 $contact->PostalAddressID( $postaladdressID );
 $postaladdressID = $contact->PostalAddressID;


Prefix

Return or set the Prefix information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the Prefix
   (default: no change)
Output Parameters

 1 current/old name of the Prefix
Example

 $contact->Prefix( 'van' )
 $prefix = $contact->Prefix;


SortName

Return or set the SortName information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the SortName
   (default: no change)
Output Parameters

 1 current/old name of the SortName
Example

 $contact->SortName( 'mattijsenelizabeth' );
 $sortName = $contact->SortName;


Status

Return or set the Status information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the Status
   (default: no change)
Output Parameters

 1 current/old name of the Status
Example

 $contact->Status( 1 );
 $status = $contact->Status;


Phone

Return or set the Phone information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the Phone number
   (default: no change)
Output Parameters

 1 current/old name of the Phone number
Example

 $contact->Phone( '+31 20 6005700' );
 $phone = $contact->Phone;


Position

Return or set the Position information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the Position
   (default: no change)
Output Parameters

 1 current/old name of the Position
Example

 $contact->Position( 'President' );
 $Position = $contact->Position;


Title

Return or set the Title information of the Liz::OCASet::Contact object.

Input Parameters

 1 new name of the Title
   (default: no change)
Output Parameters

 1 current/old name of the Title
Example

 $contact->Title( 'Drs.' );
 $title = $contact->Title;


Updated

Return the Updated information of the Liz::OCASet::Contact object.

Output Parameters

 1 current timestamp of the Updated
Example

 $updated = $contact->Updated;


URL

Specify or return the URL associated with the Liz::OCASet::Contact object.

Input Parameters

 1 new value of the URL
   (default: no change)
Output Parameters

 1 previous/current version of the URL
Example

 $contact->URL( 'http://www.xxLINK.nl/em.htm' );
 $url = $contact->URL;


EXTRA EMAIL ADDRESS METHODS

The following methods allow extra email addresses to be associated with the object.


AddExtraEmail

Associate an extra email address with the object. Optionally specify a type of email address.

If the email address existed already as an extra email address for the specified ID, then only the type of extra email address will be updated (if specified).

Use method ExtraEmail to return which email addresses are associated with the object.

Input Parameters

 1    type of extra email address (optional)
      (default: none, text may not contain @ as that indicates a valid email address)
 2..N extra email addresses to add
Example

 $contact->AddExtraEmail( 'liz@inc.nl' );
 $contact->AddExtraEmail( 'old','liz@iksx.nl' );
 $contact->AddExtraEmail( 'home','liz@metal.xxLINK.nl' );


DeleteExtraEmail

Delete one, more or all email address(es) that are associated with the object. Optionally specify a type of email address.

If the email address existed already as an extra email address for the specified ID, then only the type of extra email address will be updated (if specified).

Use method ExtraEmail to return which email addresses are associated with the object.

Input Parameters

 1    type of extra email address to remove (optional)
      (default: all types, may not contain @'s as they indicate email addresses)
 2..N extra email addresses to delete
      (default: all of specified type)
Example

 $contact->DeleteExtraEmail;
 $contact->DeleteExtraEmail( 'old' );
 $contact->DeleteExtraEmail( 'liz@metal.xxLINK.nl' );


ExtraEmail

Return a reference to a list of extra email addresses associated with the object. Optionally returns a reference to a hash with email address types, keyed to the email address.

Use method AddExtraEmail to add an extra email address. Use method DeleteExtraEmail to delete extra email address.

Input Parameters

 1 type of extra email address to return list of (optional)
   (default: all types, may not contain @'s as they indicate email addresses)
Output Parameters

 1 reference to a list of email addresses
 2 reference to a hash with email address type
Example

 ($email,$type) = $contact->ExtraEmail;
 foreach( @{$email} ) {
   print "$_ ($$type{$_})\n";
 }


ExtraEmailType

Return a list of types of extra email address types currently defined (e.g. handy for pulldown menu's or radio buttons) or to return the extra email type of a specific extra email address.

Input Parameters

 1    extra email address to return type of
      (default: return all possible extra email types)
 2    ID to which the extra email address belongs
      (default: ID of object itself)
Output Parameters

 1..N types of extra email currently available
Example

 $extraemailtype = $contact->ExtraEmailType( $extraemail );
Example

 @types = $contact->ExtraEmailType;
Note

Does not return the empty extra email type, even if extra email addresses exist without specific type.


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1998-2000 International Network Consultants


HISTORY

Version 0.52, 14 June 2000

Fixed problem in new that would cause an error if the specified ID did not exist (missing ``no strict qw(refs)'').

Version 0.51, 25 November 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method Address.

Version 0.50, 30 September 1999

Now no longer adds Exporter to ISA: it wasn't necessary.

Version 0.49, 24 July 1999

Removed inheritance of fields EXTRAFIELDS_ALPHA and EXTRAFIELDS_NUMERIC from new as it is not needed and it causes problems.

Version 0.48, 13 May 1999

Fixed problem in update that would cause the ``created'' timestamp not to be set for new records.

Version 0.47, 12 May 1999

Method new now sets global variable $ERROR if something went wrong obtaining the fields of an existing record.

Adapted methods new and update so that they can be sub-classed with extra fields.

Changed the typography of the source to the new indented format.

Version 0.46, 4 May 1999

Fixed problem with ForeignKey not being set after an update( 1 ).

Version 0.45, 27 April 1999

Fixed problem in method update which would not return the ID of the object if the object was not changed.

Version 0.44, 27 April 1999

Fixed problem with ForeignKey not being set for existing records.

Version 0.43, 13 April 1999

Method Address now allows ``0'' to be specified to create a new Address object, instead of using the default AddressID.

Version 0.42, 4 April 1999

Added method ExtraEmailType: returns list of extra email types currently available.

Fixed problem in update that would merge contacts with the same name but with different email addresses if the email address did not occur in the table yet.

Version 0.41, 3 April 1999

Method Name now directly calls Liz::Name to by-pass the method by the same name in Liz::OCASet.

Now inherits from Liz::OCASet instead of Liz::SQL.

Added support for the IP method, which returns the IP-number from which the record was created or last changed.

Added support for the IP field in the database structure.

Version 0.4, 2 April 1999

Added support for ExtraEmail, AddExtraEmail and DeleteExtraEmail added which allows associating extra email addresses with the object.

Version 0.32, 9 January 1999

Fixed problem in method new that would cause the Address sub-object to store categories on the top level, instead of under the Liz::OCASet category.

Version 0.31, 17 December 1998

Method Address added to create the address object associated with the Contact object.

Now uses the field ``TOKEN'' and the internal subroutine RawTableName to create the name of the database table.

Version 0.3, 14 October 1998

Support for ForeignKey added.

Version 0.21, 6 October 1998

Reduced memory footprint by using fully qualified global variables only.

Version 0.2, 30 September 1998

Support for URL added.

Version 0.1, 28 September 1998

First version of this true Perl module.