/ 
SPOPS-0.50
River stage one • 2 direct dependents • 2 total dependents
/ SPOPS::ClassFactory::DBI

NAME

SPOPS::ClassFactory::DBI - Define additional configuration methods

SYNOPSIS

# Put SPOPS::DBI in your isa
my $config = {
      class => 'My::SPOPS',
      isa   => [ 'SPOPS::DBI::Pg', 'SPOPS::DBI' ],
};

DESCRIPTION

This class implements a behavior for the 'links_to' slot as described in SPOPS::ClassFactory.

It is possible -- and perhaps desirable for the sake of clarity -- to create a method within SPOPS::DBI that does all the work that this behavior does, then we would only need to create a subroutine that calls that subroutine.

However, creating routines with the values embedded directly in them should be quicker and more efficient. So we will try it this way.

METHODS

Note: Even though the first parameter for all behaviors is $class, they are not class methods. The parameter refers to the class into which the behaviors will be installed.

conf_relate_links_to( $class )

Slot: links_to

Get the config for $class and find the 'links_to' configuration information. If defined, we auto-generate subroutines to implement the linking functionality.

Typical configuration:

my $config = {
      class => 'My::SPOPS',
      isa   => [ 'SPOPS::DBI::Pg', 'SPOPS::DBI' ],
      links_to => { 'My::Group' => 'link-table' },
};

This assumes that 'My::OtherClass' has already been created or will be part of the same configuration sent to SPOPS::ClassFactory (or more likely SPOPS::Initialize).

All subroutines generated use the alias used by SPOPS for the class specified in the key. For instance, in the above configuration example we give 'My::Group' as the class specified in the key. So to get the alias for this class we do:

my $alias = My::Group->CONFIG->{main_alias};

We then use $alias to define our method names.

The first method generated is simply named $alias. The method returns an arrayref of objects that the main object links to. For instance:

Example:

# $links_to = 'My::Group' => 'link-table'
# Alias for 'My::Group' = 'group'

my $object = My::SPOPS->fetch( $id );
my $group_list = eval { $object->group };

The second is named '${alias}_add' (e.g., 'group_add') and links the object to any number of other objects. The return value is the number of successful links.

The third is named '${alias}_remove' (e.g., 'group_remove') and removes links from the object to any number of other objects. The return value is the number of successful removals.

Examples:

# First retrieve all groups
my $object = My::SPOPS->fetch( $id );
my $group_list = eval { $object->group };
print "Group list: ", join( ' // ', map { $_->{group_id} } @{ $group_list } );

>> 2 // 3 // 5

# Now add some more, making the thingy a member of these new groups

my $added = eval { $object->group_add( [ 7, 9, 21, 23 ] ) };
print "Group list: ", join( ' // ', map { $_->{group_id} } @{ $group_list } );

>> 2 // 3 // 5 // 7 // 9 // 21 // 23

# Now remove two of them

my $removed = eval { $object->group_remove( [ 2, 21 ] ) };
print "Group list: ", join( ' // ', map { $_->{group_id} } @{ $group_list } );

>> 3 // 5 // 7 // 9 // 23

CONFIGURATION FIELDS EXPLAINED

base_table ($) (used by SPOPS::DBI)

Table name for data to be stored.

sql_defaults (\@) (used by SPOPS::DBI)

List of fields that have defaults defined in the SQL table. For instance:

active   CHAR(3) DEFAULT 'yes',

After SPOPS::DBI fetches a record, it then checks to see if there are any defaults for the record and if so it refetches the object to ensure that the data in the object and the data in the database are synced.

field_alter (\%) (used by SPOPS::DBI)

Allows you to define different formatting behaviors for retrieving fields. For instance, if you want dates formatted in a certain manner in MySQL, you can do something like:

field_alter => { posted_on => q/DATE_FORMAT( posted_on, '%M %e, %Y (%h:%i %p)' )/ }

Which instead of the default time format:

2000-09-26 10:29:00

will return something like:

September 26, 2000 (10:29 AM)

These are typically database-specific.

Relationship Fields

links_to (\%)

The 'links_to' field allows you to specify a SPOPS alias and specify which table is used to link the objects:

{
   'SPOPS-class' => 'table_name',
}

Note that this relationship assumes a link table that joins two separate tables. When you sever a link between two objects, you are only deleting the link rather than deleting an object. See "TO DO" for another proposal.

TO DO

Make 'links_to' more flexible

We need to account for different types of linking; this may require an additional field beyond 'links_to' that has a similar effect but works differently.

For instance, Table-B might have a 'has_a' relationship with Table-A, but Table-A might have a 'links_to' relationship with Table-B. (Themes in OpenInteract work like this.) We need to be able to specify that when Table-A severs its relationship with one or more objects from Table-B, the actual object is removed rather than just a link between them.

BUGS

None known.

COPYRIGHT

Copyright (c) 2001 intes.net, inc.. All rights reserved.

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

AUTHORS

Chris Winters <chris@cwinters.com>

See the SPOPS module for the full author list.