NAME

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


SYNOPSIS

 use xxLINK;
 $xxlink = new xxLINK;
 $ocaset = $xxlink->OCASet( 'customers' );
 
 $organization = $ocaset->Organization;
 $organization = $ocaset->Organization( $organizationID );

 $name = $organization->Name;
 $addressID = $organization->AddressID;
 $organizationID = $organization->OrganizationID;

 $organizationID = $organization->update;


DESCRIPTION

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


BASIC METHODS


new

Create a new Organization object from a client module object.

Input Parameters

 1 Liz::SQL object
 2 Name/ID to create Organization object with
 3 if 2==name: Department to create Organization with
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' );
 $organization = $ocaset->Organization;
 $organization = $ocaset->Organization( 'xxLINK Internet Services' );
 $organization = $ocaset->Organization( $organizationID );


update

Update a Organization object in the database.

Input Parameters

 1 flag: whether to really add (0=add, 1=obtain ID if available, no update)
   (default: add)
Output Parameters

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

 $organization->update;


delete

Delete the record in the database associated with the Organization object, and all records associate with the Organization, unless inhibited.

Input Parameters

 1 flag: inhibit deletion of associated Contact and Organization records
   (default: delete all)
Output Parameters

 1 flag: whether action was successful
Example

 $organization->delete;
 $organization->delete( 1 );


CONTENT METHODS

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


Address

Create a new 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 of Organization, 0 to indicate new Address object)
Output Parameters

 1 instantiated Liz::OCASet::Address object
Example

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


AddressID

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

Input Parameters

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

 1 current/old value of the AddressID
Example

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


ContactID

Return or set the ContactID information of the Liz::OCASet::Organization object.

Input Parameters

 1 new ID of the ContactID
   (default: no change)
Output Parameters

 1 current/old ID of the ContactID
Example

 $organization->ContactID( $contactID );
 $contactID = $organization->ContactID;


Created

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

Output Parameters

 1 current timestamp of the Created
Example

 $created = $organization->Created;


Data

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

Input Parameters

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

 1 current/old name of the Data
Example

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


Department

Return or set the Department information of the Liz::OCASet::Organization object.

Input Parameters

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

 1 current/old name of the Department
Example

 $organization->Department( 'Software Development' );
 $department = $organization->Department;


Email

Return or set the Email information of the Liz::OCASet::Organization 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;


Employee

Create a Contact object for a specified Employee (a Contact that has the ID of the object specified as its OrganizationID).

Input Parameters

 1 ID to create Employee with
Output Parameters

 1 instantiated Liz::Contact object
Example

 foreach ($organization->EmployeeIDs) {
   $employee = $organization->Employee( $_ );
 }


EmployeeIDs

Return the list of contactIDs that have the Organization of the object specified as its parent.

Input Parameters

 1    extra WHERE information
      (default: none)
 2    extra ORDER information
      (default: none)
 3    extra LIMIT information
      (default: none)
Output Parameters

 1..N contactID's
Examples

 foreach ($ocaset->EmployeeIDs) {
  print "$_\n";
 }


Employees

Return an SQL-statement(-like) handle that contains a selection of the Employees available in the OCA set.

An Employee is defined as a Contact that has its OrganizationID field set to the ID of the object.

The following field names can be specified with the first parameter:

 ID
 The ID of the Employee.  Can be used as parameter on the L<Contact>
 method of the OCASet.

 email
 The email address of the Employee, e.g. 'wendy@xxLINK.nl'.

 name
 The name (either last name or complete name, depending on implementation)
 of the Employee, e.g. 'Dijk'.

 firstname
 The first name of the Employee, e.g. 'Wendy'.

 prefix
 The prefix of the last name of the Employee, e.g. 'van'.

 phone
 The phone number of the Employee.

 fax
 The fax number of the Employee.

 status
 The status of the Employee: this can be any number between 0 and 255 inclusive.
 Status 255 usually means "automatic addition, should be reviewed".

 updated
 Timestamp when the Employee record was last updated in the database.

 created
 Timestamp when the Employee record was created in the database.

 sortname
 The string on which the Employee can be sorted.  It usually consists of
 the name field, followed by the firstname and prefix field, all in
 lowercase and with all non-alphanumeric characters removed.

 addressID
 The ID of the Address information of the Employee.  If non-zero, can be
 used to create an L<Address> object with.

 organizationID
 The ID of the Organization information of the Employee.  If non-zero, can be
 used to create an L<Organization> object with.

 genderID
 The ID of the Gender of the Employee.  Can be changed to the appropriate
 string by using the L<IDs2Strings> method.

 titleID
 The ID of the Title of the Employee.  Can be changed to the appropriate
 string by using the L<IDs2Strings> method.

 positionID
 The ID of the Position of the Employee.  Can be changed to the appropriate
 string by using the L<IDs2Strings> method.

 options
 The Options associated with the Employee.  Meaning of the options is
 entirely up to the implementation.

 data
 The extra Data associated with the Employee.  Meaning of the data is
 entirely up to the implementation.

 IP
 Packed IP-number from where the record was last updated
Input Parameters

 1 fields to return for each Contact, seperated by comma's
   (default: 'ID,email,name,firstname,prefix,phone,fax,status,updated,created,sortname,addressID,organizationID,genderID,titleID,positionID,options,data,IP')
 2 extra SQL condition to apply
   (default: none)
 3 order in which to return the finds
   (default: sortname)
 4 which records should be returned
   (default: all )
Output Parameters

 1 SQL-like statement handle (on which method "fetchrow" can be applied)
Examples

 $result = $organization->Employees;
 $result = $organization->Employees( 'firstname,prefix,name,email','status=255' );


Fax

Return or set the Fax information of the Liz::OCASet::Organization 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;


ForeignKey

Return or set the ForeignKey information of the Liz::OCASet::Organisation object. A foreign key is nothing else than another descriptor of the object. It is usually used if the Organisation 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

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


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::Organization object.

Input Parameters

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

 1 current/old name of the Name
Example

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


Options

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

Input Parameters

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

 1 current/old name of the Options
Example

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


OrganizationID

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

Input Parameters

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

 1 current/old value of the OrganizationID
Example

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


Phone

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

Input Parameters

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

 1 current/old name of the Phone number
Example

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


PostalAddressID

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

Input Parameters

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

 1 current/old value of the PostalAddressID
Example

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


SortName

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

Input Parameters

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

 1 current/old name of the SortName
Example

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


Status

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

Input Parameters

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

 1 current/old name of the Status
Example

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


SubOrganization

Create an Organization object for a specified SubOrganization.

Input Parameters

 1 ID to create SubOrganization with
Output Parameters

 1 instantiated Liz::OCASet object
Example

 foreach ($organization->SubOrganizationIDs) {
   $suborganization = $organization->SubOrganization( $_ );
 }


SubOrganizations

Return an SQL-statement(-like) handle that contains a selection of the Organizations available in the OCA set which have the Organization of the object specified as their OrganizationID.

The following field names can be specified with the first parameter:

 ID
 The ID of the Organization.  Can be used as parameter on the L<Organization>
 method.

 email
 The email address of the Organization, e.g. 'info@xxLINK.nl'.

 name
 The name of the Organization, e.g. 'xxLINK Internet Services'.

 phone
 The phone number of the Organization.

 fax
 The fax number of the Organization.

 status
 The status of the Organization: this can be any number between 0 and 255
 inclusive.  Status 255 usually means "automatic addition, should be reviewed".

 updated
 Timestamp when the Organization record was last updated in the database.

 created
 Timestamp when the Organization record was created in the database.

 sortname
 The string on which the Organization can be sorted.  It usually consists of
 the name field in lowercase and with all non-alphanumeric characters removed.

 addressID
 The ID of the Address information of the Organization.  If non-zero, can be
 used to create an L<Address> object with.

 contactID
 The ID of the main Contact information of the Organization.  If non-zero,
 can be used to create a L<Contact> object with.

 typeID
 The ID of the Type of the Organization.  Can be changed to the appropriate
 string by using the L<IDs2Strings> method.

 options
 The Options associated with the Organization.  Meaning of the options is
 entirely up to the implementation.

 data
 The extra Data associated with the Organization.  Meaning of the data is
 entirely up to the implementation.

 department
 The Department associated with the Organization.

 IP
 Packed IP-number from where the record was last updated.

 url
 The URL associated with the organization.
Input Parameters

 1 fields to return for each Organization, seperated by comma's
   (default: 'ID,email,name,phone,fax,status,updated,created,sortname,addressID,contactID,typeID,options,data,department,IP,url')
 2 extra SQL condition to apply
   (default: none)
 3 order in which to return the finds
   (default: sortname)
 4 which records should be returned
   (default: all )
Output Parameters

 1 SQL-like statement handle (on which method "fetchrow" can be applied)
Examples

 $result = $ocaset->Organizations;
 $result = $ocaset->Organizations( 'name,email','status=255' );


SubOrganizationIDs

Return the list of organizationIDs that have the Organization of the objecy specified as its parent.

Input Parameters

 1    extra WHERE information
      (default: none)
 2    extra ORDER information
      (default: none)
 3    extra LIMIT information
      (default: none)
Output Parameters

 1..N organizationID's
Examples

 foreach ($ocaset->SubOrganizationIDs) {
  print "$_\n";
 }


Type

Return or set the Type information of the Liz::OCASet::Organization object.

Input Parameters

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

 1 current/old name of the Type
Example

 $organization->Type( 'Internet Presence Provider' );
 $type = $organization->Type;


Updated

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

Output Parameters

 1 current timestamp of the Updated
Example

 $updated = $organization->Updated;


URL

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

Input Parameters

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

 1 previous/current version of the URL
Example

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


EXTRA EMAIL 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

 $organization->AddExtraEmail( 'liz@inc.nl' );
 $organization->AddExtraEmail( 'old','liz@iksx.nl' );
 $organization->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

 $organization->DeleteExtraEmail;
 $organization->DeleteExtraEmail( 'old' );
 $organization->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 = $organization->ExtraEmailType( $extraemail );
Example

 @types = $organization->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-1999 International Network Consultants


HISTORY

Version 0.60, 25 November 1999

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

Version 0.59, 30 September 1999

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

Version 0.58, 8 August 1999

Localised method delete so that it will delete all SubOrganizations and Employees that are associated with the object, unless inhibited.

New methods SubOrganization and Employee allow creation of Organization and Contact object related to the object.

Method new now no longer adds the extra fields to the allowed list twice.

New methods SubOrganizations and SubOrganizationIDs added which return information about the Organizations that have the object's Organization specified as their OrganizationID.

Version 0.57, 24 July 1999

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

Version 0.56, 12 May 1999

Changed method new so that global variable $ERROR is now set with an error message if obtaining the data of an existing record failed.

Updated methods new and update so that this module can be sub-classed with extra fields.

Changed typography of the source to the new indented format.

Version 0.55, 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.54, 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.53, 5 April 1999

New method Employees added: returns an SQL-like handle for all the Contacts that have this Organization as its OrganizaionID.

Version 0.52, 4 April 1999

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

Version 0.51, 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.5, 2 April 1999

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

Version 0.45, 28 January 1999

Fixed problem that would cause the ForeignKey not to be obtained from the table into the object.

Version 0.44, 9 January 1999

Fixed problem in method new that would cause the sub-object Address to store categories at the top level rather than under the Liz::OCASet category.

Version 0.43, 17 December 1998

Added method Address to create a Liz::OCASET::Address object associated with the Organization.

Now uses the ``TOKEN'' field and internal subroutine RawTableName for creation of database table name.l subroutine RawTableName for creation of database table name.

Version 0.42, 15 December 1998

Fixed problem with Department being double quoted.

Support for OrganizationID added.

Version 0.41, 30 November 1998

Internal subroutine RawTableName added.

Version 0.4, 14 October 1998

Support for ForeignKey added.

Version 0.31, 6 October 1998

Reduced memory footprint by using fully qualified global variables only.

Version 0.3, 4 October 1998

Support for Department added.

Version 0.2, 30 September 1998

Support for URL added.

Version 0.1, 28 September 1998

First version of this true Perl module.