Magnus Erixzon > WWW-Google-Contacts > WWW::Google::Contacts::Contact

Download:
WWW-Google-Contacts-0.38.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  2
View/Report Bugs
Module Version: 0.38   Source  

SYNOPSIS ^

    use WWW::Google::Contacts;

    my $google = WWW::Google::Contacts->new( username => "your.username", password => "your.password" );

    my $contact = $google->new_contact;
    $contact->full_name("Emmett Brown");

A lot of fields, such as email, phone number and so on, are accessible as array refs.

    foreach my $email (@{ $contact->email }) {
       print "He got email address: " . $email->value . "\n";
    }

When you have made changes to your contact, you need to save them back to Google. This is done either by a create call (for new contacts) or an update call (for existing contacts).

    $contact->create;

Alternatively, you can use the create_or_update method, which will do the right thing.

    $contact->create_or_update;

METHODS ^

$contact->create

Writes the contact to your Google account.

$contact->retrieve

Fetches contact details from Google account.

$contact->update

Updates existing contact in your Google account.

$contact->delete

Deletes contact from your Google account.

$contact->create_or_update

Creates or updates contact, depending on if it already exists.

ATTRIBUTES ^

All these attributes are gettable and settable on Contact objects.

given_name

 $contact->given_name("Arnold");

additional_name

 $contact->additional_name("J");

family_name

 $contact->family_name("Rimmer");

name_prefix

 $contact->name_prefix("Mrs");

name_suffix

 $contact->name_suffix("III");

full_name

If this is set to what seems like "$given_name $family_name", those attributes will be automatically set.

email

$contact->email is, if defined, an array reference with 1 or more Email objects. The Email objects have the following accessors;

type

This is an object in itself, which has 2 accessors; name and uri.

label

If you don't want to use the predefined types (defined by Google) you can set this label instead.

value

The email address.

display_name

An optional display name.

primary

A boolean stating whether this is the primary email address.

Example code (set the first work email as the primary address):

 foreach my $email (@{ $contact->email }) {
   if ( $email->type->name eq 'work' ) {
     $email->primary(1);
     last;
   }
 }

Explicitly setting all email details:

 $contact->email({
   type => "work",
   value => 'shenanigans@example.com',
   display_name => 'Shenanigans',
   primary => 1,
 });

Note that this will overwrite any previous email addresses for the contact. To add rather than replace, see add_email below.

If you're just setting the email value, type will default to "work" and leave other fields empty.

 $contact->email( 'smeghead@reddwarf.net' );

To specify several email addresses, you could either;

phone_number

$contact->phone_number is, if defined, an array reference with 1 or more PhoneNumber objects. The PhoneNumber objects have the following accessors;

type

This is an object in itself, which has 2 accessors; name and uri.

label

If you don't want to use the predefined types (defined by Google) you can set this label instead.

value

The phone number

Explicitly setting all phone details:

 $contact->phone_number({
   type => "mobile",
   value => "+449812323",
 });

Just setting the value will set type to default value "mobile".

 $contact->phone_number( "+1666666" );

To specify several phone numbers, you could either;

im (Instant Messaging)

$contact->im is, if defined, an array reference with 1 or more IM objects. The IM objects have the following accessors;

type

This is an object in itself, which has 2 accessors; name and uri.

label

If you don't want to use the predefined types (defined by Google) you can set this label instead.

protocol

This is an object in itself, which has 2 accessors; name and uri.

Which protocol is used for this IM address. Possible name values include AIM, MSN, YAHOO. SKYPE, QQ, GOOGLE_TALK, ICQ, JABBER.

value

Email address for the IM account.

You can specify all IM details:

 $contact->im({
   type => "home",
   protocol => "MSN",
   value => 'some.email@example.com',
 });

Or you can just choose to give the IM address:

 $contact->im( 'some.email@example.com' );

organization

$contact->organization is, if defined, an array reference with 1 or more Organization objects. The Organization objects have the following accessors;

type

This is an object in itself, which has 2 accessors; name and uri.

label

If you don't want to use the predefined types (defined by Google) you can set this label instead.

department

Specifies a department within the organization.

job_description

Description of a job within the organization.

name

The name of the organization.

symbol

Symbol of the organization.

title

The title of a person within the organization.

primary

Boolean. When multiple organizations extensions appear in a contact kind, indicates which is primary. At most one organization may be primary.

where

A place associated with the organization, e.g. office location.

postal_address

$contact->postal_address is, if defined, an array reference with 1 or more PostalAddress objects. The PostalAddress objects have the following accessors;

type

This is an object in itself, which has 2 accessors; name and uri.

label

If you don't want to use the predefined types (defined by Google) you can set this label instead.

mail_class

This is an object in itself, which has 2 accessors; name and uri.

Classes of mail accepted at the address. Possible name values are both, letters, parcels and neither. Unless specified both is assumed.

usage

This is an object in itself, which has 2 accessors; name and uri

The context in which this addess can be used. Possible values are general and local. Local addresses may differ in layout from general addresses, and frequently use local script (as opposed to Latin script) as well, though local script is allowed in general addresses. Unless specified general usage is assumed.

primary

Boolean. Specifies the address as primary.

agent

The agent who actually receives the mail. Used in work addresses. Also for 'in care of' or 'c/o'.

house_name

Used in places where houses or buildings have names (and not necessarily numbers), eg. "The Pillars".

street

Can be street, avenue, road, etc. This element also includes the house number and room/apartment/flat/floor number.

pobox

Covers actual P.O. boxes, drawers, locked bags, etc. This is usually but not always mutually exclusive with street.

neighborhood

This is used to disambiguate a street address when a city contains more than one street with the same name, or to specify a small place whose mail is routed through a larger postal town. In China it could be a county or a minor city.

city

Can be city, village, town, borough, etc. This is the postal town and not necessarily the place of residence or place of business.

subregion

Handles administrative districts such as U.S. or U.K. counties that are not used for mail addressing purposes. Subregion is not intended for delivery addresses.

region

A state, province, county (in Ireland), Land (in Germany), departement (in France), etc.

postcode

Postal code. Usually country-wide, but sometimes specific to the city (e.g. "2" in "Dublin 2, Ireland" addresses).

country

An object with two accessors; name and code.

formatted

The full, unstructured postal address.

billing_information

Specifies billing information of the entity represented by the contact.

notes

Arbitrary notes about your friend.

 $contact->notes( "He's a lumberjack, but he's ok" );

birthday

If defined, returns an object with one accessor;

when

Birthday date, given in format YYYY-MM-DD (with the year), or --MM-DD (without the year).

...tba

Sorry, haven't documented all attributes yet :(

INTERACTION WITH GROUPS ^

Contacts can belong to 0 or more groups. This section describes how to get and set group memberships.

$contact->groups

Returns an array reference of all groups, as WWW::Google::Contacts::Group objects.

$contact->add_group_membership( group )

The group argument can either be:

An WWW::Google::Contacts::Group object
The ID of a group, as a URL
The name of a group

Do note that the group has to exist on the Google servers before you can add this membership.

AUTHOR ^

 Magnus Erixzon <magnus@erixzon.com>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2010 by Magnus Erixzon.

This is free software; you can redistribute it and/or modify it under the same terms as perl itself.

syntax highlighting: