NAME

    pkg('Contrib') - storage and retrieval of contributor data

SYNOPSIS

    # create new contributor object
    my $contrib = pkg('Contrib')->new(  prefix => 'Mr.',
                                        first => 'Matthew',
                                        middle => 'Charles',
                                        last => 'Vella',
                                        email => 'mvella@thepirtgroup.com',
                                        phone => '111-222-3333',
                                        bio => 'This is my bio.',
                                        url => 'http://www.myurlhere.com' );

    # add contributor types (lets pretend contrib_type 1 is 'Writer' and 
    # type 3 is 'Photographer')
    $contrib->contrib_type_ids(1,3);

    # save this contributor to the database
    $contrib->save();

    # now that it is saved we can get its id
    my $contrib_id = $contrib->contrib_id();

    # find this contributor by id
    my @contribs = pkg('Contrib')->find( contrib_id => $contrib_id );

    # list contributor type ids (will return 1,3)
    @contrib_type_ids = $contribs[0]->contrib_type_ids();

    # list contrib type names (will return 'Writer', 'Photographer');
    @contrib_type_names = $contribs[0]->contrib_type_names();

    # change contributor contrib type ids, effectively removing writer type (1)
    $contribs[0]->contrib_type_ids(3);

    # save contributor, making changes permanent
    $contribs[0]->save();

    # delete contributor
    $contribs[0]->delete();

DESCRIPTION

This class handles the storage and retrieval of contributor data to/from the database. Contributor type ids come from Krang::AdminPrefs (??), but are associated to contributors here.

INTERFACE

METHODS

• $contrib = Krang::Contrib->new()
  
new() suports the following name-value arguments:
• prefix
  
• first
  
• middle
  
• last
  
• suffix
  
• email
  
• phone
  
• bio
  
• url
  
All of the above are simply fields for storing arbitrary metadata

• $contrib_id = $contrib->contrib_id()
  
Returns the unique id assigned the contributor object. Will not be populated until $contrib->save() is called the first time.
• $contrib->prefix()
  
• $contrib->first()
  
• $contrib->middle()
  
• $contrib->last()
  
• $contrib->suffix()
  
• $contrib->email()
  
• $contrib->phone()
  
• $contrib->bio()
  
• $contrib->url()
  
Gets/sets the value.
• $contrib->full_name()
  
A read-only method that returns a concatenated string containing all attributes that make up the contributor's name. Any unassigned attributes will be omitted.

full_name takes the form of: prefix() first() middle() last(), suffix()

• $contrib->image()
  
Returns the Krang::Media object associated with this contributor. Passing a Krang::Media object sets the media object associated with this contributor (overwriting any current image).
• $contrib->selected_contrib_type()
  
Temporary value used by assets (media, story, etc) to show which contrib type the contrib object they are referring belongs to. Contains a single contrib_type_id from contrib_type_ids.
• $contrib->contrib_type_ids()
  
Returns an array of contrib_type_id's associated with this contributor. Passing in array of ids sets them (overwriting any current type ids).
• $contrib->contrib_type_names()
  
Returns array of contrib type names, matching order of contrib_type_ids.
• $contrib->save()
  
Save contributor oject to the database. Will set contrib_id if first save.

Contributor names much be unique. Specifically, no two contributors many have the same first, middle, and last name. If you attempt to save a duplicate contributor $contrib->save() will throw an exception or type Krang::Contrib::DuplicateName. This exception provides a contrib_id of the existing contributor who already has this name.

• $contrib->delete() || Krang::Media->delete($contrib_id)
  
Permanently delete contrib object or contrib object with given id and contrib type associations.
• @contrib = Krang::Contrib->find($param)
  
Find and return contributors with with parameters specified. Supported paramter keys:
contrib_id
first
last
simple_search - will search first, middle, last for matching LIKE strings
exclude_contrib_ids - pass array ref of IDs to be excluded from the result set
order_by - field(s) to order search by, defaults to last,first. Can pass in list.
order_desc - results will be in ascending order unless this is set to 1 (making them descending).
limit - limits result to number passed in here, else no limit.
offset - offset results by this number, else no offset.
ids_only - return only contrib_ids, not objects if this is set true.
count - return only a count if this is set to true. Cannot be used with ids_only.

• $contrib->serialize_xml(writer => $writer, set => $set)
  
Serialize as XML. See Krang::DataSet for details.
• $contrib = Krang::Contrib->deserialize_xml(xml => $xml, set => $set, no_update => 0)
  
Deserialize XML. See Krang::DataSet for details.

If an incoming contributor has the same first, middle and last name as an existing contributor then deserialize_xml() will update the contributor object rather than create a new one.