Liz::OCASet - Organization/Contact/Address module
The Liz::OCASet package allows for very simple storage of sets of Organization, Contact and Address information. It can be used to create mailing lists (together with the Liz::BulkMail module) or to create databases of relations.
It can be used anywhere where you would want to keep more than just an email address and a name for a contact. But even then, the Liz::OCASet module might be a better choice because it will allow you to expand easily to more types of information should you need to do that.
The Liz::OCASet module contains three sub-modules:
Liz::OCASet::Organization This module contains all information pertaining to organization. Each organization can have links to two addresses and one contact.
Liz::OCASet::Contact This module contains all information pertaining to a contact person. Each contact can have links to two addresses and one organization.
Liz::OCASet::Address This module contains all information about geographic locations such as street, zipcode, city, state and country.
The Liz::OCASet module internally uses the Liz::CategorySet module to store different types of information. This allows for a more compact storage of information such as cities, states, countries, gender, title, position and type of organization: these are all stored as a categoryID rather than as a string. All methods that are used by the developer however, hide this fact almost entirely from day-to-day usage.
The Liz::OCASet module itself works best when incorporated into a client module because it moves the responsibility of aquiring a connection to a database to the client module and it allows any customisation to take place transparently to the developer.
Take for example the OCASet method of xxLINK.pm module:
sub OCASet {
# Obtain the parameters # Start the category using the $xxlink handle as the database handle # Return the finished object
my( $xxlink,$token ) = @_; my( $ocaset ) = Liz::OCASet->new( $token,$xxlink ); $ocaset; }
Because of the above code in xxLINK.pm, it is now possible to write the following code:
$xxlink = new xxLINK; $ocaset = $xxlink->OCASet( 'customers' );
Note that the database connection of the category is hidden in the creation
of the $xxlink object.
The following methods can be called without an object specification, but as a class method such as Liz::OCASet->method().
Return list of category identification names of all ocasets in the database specified. Usually not called by itself, but rather incorporated inside a Client Module.
Can also be used to determine whether a specific OCASet exists.
1 wildcard specification to match (default: undef = all) 2 Liz::SQL compatible handle or reference to routine that performs connect (default: &Connect from caller's namespace)
1 reference to list of identification names in the current database 2 reference to hash with full names 3 reference to hash with database versions
$xxlink = new xxLINK;
($id,$name) = $xxlink->OCASets;
$ocasets = @{$id};
print "All $ocasets ocasets in Hospitality Net:\n";
foreach( @{$id} ) {
print " OCASet '$$name{$_}' ($_)\n";
}
In xxLINK.pm:
sub OCASets { Liz::OCASet->ocasets( $_[1],$_[0] ) }
Returns whether a specific OCASet exists.
1 identification to check for 2 Liz::SQL compatible handle or reference to routine that performs connect (default: &Connect from caller's namespace)
1 flag: whether OCASet exists
$xxlink = new xxLINK;
if( $xxlink->OCASetExists( '' ) ) {
print "OCASet with default identification name exists\n";
}
In xxLINK.pm:
sub OCASetExists { Liz::OCASet->ocasetexists( $_[1],$_[0] ) }
Create a new Liz::OCASet object. Creates connection or re-establishes connection with the MySQL database. Usually not called by itself, but rather incorporated inside a Client Module.
1 identification name of ocaset (default: default ocaset for database) 2 Liz::SQL compatible handle or reference to routine that performs connect (default: &Connect from caller's namespace)
1 instantiated object 2 flag: whether the OCASet was just created
$xxlink = new xxLINK; $oca = $xxlink->OCASet( 'customers' );
In xxLINK.pm:
sub OCASet { Liz::OCASet->new( $_[1],$_[0] ) }
Delete all tables of the OCASet object. Please use this with caution, as it will destroy any information that is stored for this OCASet. If called in a void context, no tables exist for this OCASet anymore, and any references in the NextID table are also removed. Otherwise, the tables will be re-created automatically and a new object will be returned, just as if the new method was called.
1 newly created OCASet object, current object will not work anymore
$ocaset->reset;
$ocaset = $ocaset->reset;
The following methods allow changes to information that is associated with an entire ocaset.
Return the CategorySet object that is associated with the OCASet. This can be used to add further categories to Organizations, Contacts and Addresses.
1 CategorySet object
$xxlink = new xxLINK; $ocaset = $xxlink->OCASet( 'eurest' ); $categoryset = $ocaset->CategorySet;
Specify or return the current name of the ocaset object. The name can be anything to further identify the goal of the ocaset.
1 new name of ocaset (default: no change)
1 current/old name of ocaset
$xxlink = new xxLINK; $ocaset = $xxlink->OCASet( 'eurest' ); $ocaset->Name( 'Eurestjes' );
Specify or return the full name of the subroutine that is supposed to be used for authenticating users with this OCASet. This is usually the name as specified with the PerlAuthenHandler configuration parameter when using the Liz::Authenticate module for authentication.
1 new full name of the subroutine (default: no change)
1 current/old full name of the subroutine
$emailgids = new Emailgids; $ocaset = $emailgids->OCASet; $ocaset->Authenticate( 'Emailgids::MaintainAccess' );
$subroutine = $ocaset->Authenticate;
if( $subroutine ) {
$access = Liz::Authenticate->new( $subroutine )
}
The following methods return an SQL-statement(-like) handle that allows listing of (a selection of) the objects of a certain type.
Return an SQL-statement(-like) handle that contains a selection of the Addresses available in the OCA set. The following field names can be specified with the first parameter:
ID The ID of the Address. Can be used as parameter on the L<Address> method.
street The street of the Address, e.g. 'Eekholt 54'.
zipcode The zipcode of the Address, e.g. '1112 XH'.
cityID The ID of the City of the Address. Can be changed to the appropriate string by using the L<IDs2Strings> method.
stateID The ID of the State of the Address. Can be changed to the appropriate string by using the L<IDs2Strings> method.
countryID The ID of the Country of the Address. Can be changed to the appropriate string by using the L<IDs2Strings> method.
status The status of the Address: this can be any number between 0 and 255 inclusive. Status 255 usually means "automatic addition, should be reviewed".
updated Timestamp when the Address record was last updated in the database.
created Timestamp when the Address record was created in the database.
options The Options associated with the Address. Meaning of the options is entirely up to the implementation.
data The extra Data associated with the Address. Meaning of the data is entirely up to the implementation.
IP Packed IP-number from where the record was last updated
1 fields to return for each Contact, seperated by comma's (default: 'ID,street,zipcode,cityID,stateID,countryID,status,updated,created,options,data,IP') 2 extra SQL condition to apply (default: none) 3 order in which to return the finds (default: zipcode) 4 which records should be returned (default: all )
1 SQL-like statement handle (on which method "fetchrow" can be applied)
$result = $ocaset->Addresses; $result = $ocaset->Addresses( 'street,zipcode,cityID',"street LIKE '%Eekho%" );
Return an SQL-statement(-like) handle that contains a selection of the Contacts available in the OCA set. The following field names can be specified with the first parameter:
ID The ID of the Contact. Can be used as parameter on the L<Contact> method.
email The email address of the Contact, e.g. 'wendy@xxLINK.nl'.
name The name (either last name or complete name, depending on implementation) of the Contact, e.g. 'Dijk'.
firstname The first name of the Contact, e.g. 'Wendy'.
prefix The prefix of the last name of the Contact, e.g. 'van'.
phone The phone number of the Contact.
fax The fax number of the Contact.
status The status of the Contact: this can be any number between 0 and 255 inclusive. Status 255 usually means "automatic addition, should be reviewed".
updated Timestamp when the Contact record was last updated in the database.
created Timestamp when the Contact record was created in the database.
sortname The string on which the Contact 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 Contact. If non-zero, can be used to create an L<Address> object with.
organizationID The ID of the Organization information of the Contact. If non-zero, can be used to create an L<Organization> object with.
genderID The ID of the Gender of the Contact. Can be changed to the appropriate string by using the L<IDs2Strings> method.
titleID The ID of the Title of the Contact. Can be changed to the appropriate string by using the L<IDs2Strings> method.
positionID The ID of the Position of the Contact. Can be changed to the appropriate string by using the L<IDs2Strings> method.
options The Options associated with the Contact. Meaning of the options is entirely up to the implementation.
data The extra Data associated with the Contact. Meaning of the data is entirely up to the implementation.
IP Packed IP-number from where the record was last updated.
url The URL associated with the contact.
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,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 )
1 SQL-like statement handle (on which method "fetchrow" can be applied)
$result = $ocaset->Contacts; $result = $ocaset->Contacts( 'firstname,prefix,name,email','status=255' );
Return an SQL-statement(-like) handle that contains a selection of the Organizations available in the OCA set. 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.
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 )
1 SQL-like statement handle (on which method "fetchrow" can be applied)
$result = $ocaset->Organizations; $result = $ocaset->Organizations( 'name,email','status=255' );
The following methods allow creation of the various objects of the OCASet module.
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.
1 ID to create Address object with (default: new address)
1 instantiated Liz::OCASet::Address object
$xxlink = new xxLINK; $ocaset = $xxlink->OCASet( 'customers' );
$address = $ocaset->Address; $address = $ocaset->Address( $addressID );
Create a new Liz::OCASet::Contact object, either from existing information or for a new entry. For more documentation, see the Liz::OCASet::Contact object itself.
1 ID/lastname to create Contact object with (default: none = new contact) 2 firstname to create Contact object with (default: none) 3 prefix to create Contact object with (default: none) 4 sortname of contact (name on which contact should be sorted) (default: same as name if 1st parameter is name)
1 instantiated Liz::OCASet::Contact object
$xxlink = new xxLINK; $ocaset = $xxlink->OCASet( 'customers' );
$contact = $ocaset->Contact; $contact = $ocaset->Contact( 'Mattijsen','Elizabeth' ); $contact = $ocaset->Contact( $contactID );
Create a new Liz::OCASet::Organization object, either from existing information or for a new entry. For more documentation, see the Liz::OCASet::Organization object itself.
1 ID/name to create Organization object with (default: none = new organization) 2 sortname of contact (name on which organization should be sorted) (default: same as name if 1st parameter is name)
1 instantiated Liz::OCASet::Organization object
$xxlink = new xxLINK; $ocaset = $xxlink->OCASet( 'customers' );
$organization = $ocaset->Organization; $organization = $ocaset->Organization( 'xxLINK Internet Services' ); $organization = $ocaset->Organization( $organizationID );
The following methods allow extra email addresses to be associated with the ID's of the sub-objects. They're usually used internally.
Associate an extra email address with a Contact or Organization ID. 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 a Contact or Organization object.
1 ID to associate extra email address with (optional)
(default: ID of object itself)
2 type of extra email address (optional)
(default: none, text may not contain @ as that indicates a valid email address)
3..N extra email addresses to add
$ocaset->AddExtraEmail( $contactID,'liz@inc.nl' ); $ocaset->AddExtraEmail( $contactID,'old','liz@iksx.nl' ); $ocaset->AddExtraEmail( $contactID,'home','liz@metal.xxLINK.nl' );
Delete one, more or all email address(es) that are associated
with a Contact or Organization ID. 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 a Contact or Organization object.
1 ID to delete associated extra email address from (optional)
(default: ID of object itself)
2 type of extra email address to remove (optional)
(default: all types, may not contain @'s as they indicate email addresses)
3..N extra email addresses to delete
(default: all of specified type)
$ocaset->DeleteExtraEmail( $contactID ); $ocaset->DeleteExtraEmail( $contactID,'old' ); $ocaset->DeleteExtraEmail( $contactID,'liz@metal.xxLINK.nl' );
Return a reference to a list of extra email addresses associated with a Contact or Organization ID. 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.
1 ID to return extra email address of (optional) (default: ID of object itself) 2 type of extra email address to return list of (optional) (default: all types, may not contain @'s as they indicate email addresses)
1 reference to a list of email addresses 2 reference to a hash with email address type
($email,$type) = $ocaset->ExtraEmail( $contactID );
foreach( @{$email} ) {
print "$_ ($$type{$_})\n";
}
Return an SQL handle for a list of all the extra email addresses that are available. Optionally allows for checking only certain ID's, email addresses or extra emailtype's.
1 fields to be returned (default: ID,email,emailtypeID) 2 extra SQL to use in query (default: none)
1 SQL result handle
($list,$hash) = $ocaset->ExtraEmailType2ListHash;
$result = $ocaset->ExtraEmailList;
while (($ID,$email,$emailtypeID) = $result->fetchrow) {
print "$email belongs to ID $ID and is of type '$$hash{$emailtypeID}'\n";
}
Return a list of types of extra email address types currently defined (e.g. handy for pulldown menu's or radio buttons) or return the extra email type of a specific extra email address.
1..N types of extra email currently available
@types = $ocaset->ExtraEmailType;
Does not return the empty extra email type, even if extra email addresses exist without specific type.
Return a reference to a list with ID's of the currently available ID's for extra email types and a reference to a hash with the strings for the email types keyed to the ID's.
1 reference to list of ID's 2 reference to hash with names, keyed to ID's
($list,$hash) = $ocaset->ExtraEmailType2ListHash;
foreach (@{$list}) {
print "$$hash{$_} ($_)\n";
}
The following methods allow information to be associated with ID's of the sub-objects. They're usually used internally.
Return a reference to the (fully qualified) email addresses of the Contact or Organization ID's specified. Usually takes a call to method Values2IDs as input and is itself used as input to the To method of the Liz::BulkMail module.
1 flag: whether to return email addresses only (optional)
(default: fully qualified = 0, email addresses only = 1)
2..N ID's of Contacts or Organizations to obtain email address from
1 reference to list of (fully qualified) email addresses 2 reference to list of ID's that did not have an email address
The type of the first ID specified will determine the table searched for email addresses. It is therefore not possible to mix Contact and Organization ID's.
Obtain the values that are associated with a specific ID (either an Address, Contact or Organization object ID). Values are associated with a variable, which is either automatically set in the current namespace (when called in a void context) or returned as values from this method.
Method SetIDValues should be used to set values associated with an ID.
1 ID to associate with 2 name of variable (prefix with $ or @ to indicate scalar or list)
1..N values associated with the ID and the variable
(void: set variable in current namespace)
$language = $ocaset->GetIDValues( $ID,'$language' ); $ocaset->GetIDValues( $ID,'$language' );
Convert one or more ocaset category ID values to their associated strings. An empty string will be returned for ID value 0.
1..N ID values to be converted
1..N strings associated with the ID's
($gender,$position) = $ocaset->IDs2Strings( $genderID,$positionID );
Associate one or more values with an ID and a variable name. Use method GetIDValues to obtain the values that were previously associated with the ID and variable name
1 ID to associate values with
2 variable name to be used as key (prefix $ or @ to indicate scalar or list)
3..N values associated with the ID and variable
(none: use variable with indicated name in indicated namespace)
# use the value in the variable $taal $ocaset->SetIDValues( $ID,'language',$taal );
# use the value in the variable $language automagically $ocaset->SetIDValues( $ID,'$language' );
# use the values in the list @language automagically $ocaset->SetIDValues( $ID,'@language' );
Return the ID's with which one or more values of a variable name are associated.
1 variable name to be used as key (prefix $ or @ to indicate scalar or list)
2 flag: whether OR (0) or AND (-1) or number of matches (>0)
(default: OR)
3..N values that should be associated with the ID
(none: use values of variable with indicated name in indicated namespace)
1..N ID's that have the value of that variable associated
@ID = $ocaset->Values2IDs( '$language',0,$language ); @ID = $ocaset->Values2IDs( '$language' );
The following methods are intended to be used by tyhe submodules of the OCAset module only.
Return the IP number from where the object was last edited.
1 IP-number where record was last edited
$ip = $contact->IP;
Elizabeth Mattijsen ( lizperl@INC.nl )
(C) 1998-1999 International Network Consultants
Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method new.
Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in methods Address, Contact and Organization.
Fixed problem in new that would cause the wrong field names to be set in the associated CategorySet for the parents of ``city'', ``country'' and ``state''. Older OCASets did not suffer from this problem, just newly created ones.
Now no longer adds Exporter to ISA: it wasn't necessary.
Method new now properly uses the NameAlways2ParentIDFields method. This probably caused new entries to be added at the top level in the categoryset. Problem introduced on August 20th.
Changed method new to use the NameAlways2ParentIDFields method when applicable.
Class methods ocasets now only calls Liz:SQLs ``sets'' method.
Method new now creates an object using Liz::SQL's ``new'' method.
Adapted ExtraEmailType so that it can also return the extra email type of a specific extra email address of a specific ID, although this is only intended for the sub-classess Organization and Contact.
Adapted methods SetIDValues and GetIDValues so that they use the field PACKAGE to determine under which category the variable names should be stored.
Changed ExtraEmail to use the new ExtraEmailType2ListHash method.
Added method ExtraEmailList to return a list of extra email addresses that conform to a specific ID or type.
Added method ExtraEmailType2ListHash to create a list and hash of extra emailtype ID's and names.
Removed check for InitID in method new. This was not needed as the Liz::SQL connect method already does this. This should speed up things again a little more.
Changed all CREATE TABLEs to use the new ``create'' method of the Liz::SQL module.
Added method reset for completely resetting the entire database in one go.
Changed from using method ``Exists'' to ``Count'' in method new to more quickly find out whether a table exists or not, especially with large databases.
Upgraded typography of source to new indented format.
Method new now optionally returns a flag to indicate whether the OCASet was just created or not. This is needed to facilitate subclassing with extra fields.
Methods Contacts and Organizations did not return the ``url'' field by default. They now do.
Method methods Addresses, Contacts and Organizations inheritable from submodules.
Added method Authenticate for indicating which routine should be used for authentication.
New class method ocasetexists added: returns flag whether the OCASet with the specified identification name exists.
Changed class method ocasets so that only an undefined value will yield all possible OCASets in the database. Previously, an empty value would do this also. An empty value now is a wildcard for the OCASet with the default identification only. As such, it can also be used to check whether an OCASet with the default identification already exists in the database.
Added method ExtraEmailType: returns list of extra email types currently available.
Added support for IP numbers in tables.
Fixed problem in method ocasets which would cause the OCAset with the default token, not to be listed.
Added method ExtraEmail which returns a reference to the list of email addresses associated with a Contact or Organization object.
Added methods AddExtraEmail and DeleteExtraEmail which allow extra email addresses to be added or removed from Contact or Organization objects.
Added support for extra email addresses with Contact and Organization objects.
Checked all regular expressions and added 'o' flag when appropriate for improved speed, at the expense of extra memory.
Method EmailAddresses now allows a flag to indicate to return the bare email addresses only, instead of email address with a full name. Also, email addresses with full name information are now returned in the form
name@domain.nl (Firstname Prefix Lastname)
rather than
Firstname Prefix Lastname <name@domain.nl>
because the latter form chokes on comma's in any part of the name field.
Method ocasets now also returns a reference to a hash with the databaseversion.
Fixed problem in ocasets that would prevent the OCASet with the default identification from being listed.
Fixed problem with method new which would cause a database upgrade when a new OCASet was created.
Now internally sets field ``TOKEN'' with token of database table, so that submodules can easily create their own table names.
Support for OrganizationID added for Liz::OCASet::Organization objects. Tables are now automatically upgraded.
Method EmailAddresses now returns without generating an error if no ID's were specified.
Internal subroutine RawTableName added.
Support for ForeignKey added. This facilitates importing from external databases.
Reduced memory footprint by using fully qualified global variables only.
Moved categories associated with this module to a catogory named ``Liz::OCASet'' to prevent clashes with e.g. the Liz::ProjectSet module.
Removed internal subroutine List: now uses new TableFields2Result method of the Liz::SQL module.
Support for Organization's Department added.
Support for URL's added.
First version of this true Perl module.