/ 
SPOPS-0.37
River stage one • 2 direct dependents • 2 total dependents
/ SPOPS::Configure

NAME

SPOPS::Configure - read in configuration information for collections and create/configure

SYNOPSIS

use Ad::This;
use Ad::That;

use SPOPS::Configure;

my $classes = []; 
$classes = SPOPS::Configure->parse_config( $conf );

DESCRIPTION

This class only has one method: parse_config. It takes a hashref of collection information and configures existing classes with any information necessary (including the @ISA for each) and also whips up collection classes on the fly based on the data found in the hashref passed in.

Note that this class is not required to use SPOPS. You can happily just define the configuration information right in your class and never have a need to

METHODS

process_config( \%params )

Parameters:

config (\%)
  A hashref of configuration information for one or more SPOPS
  objects. The key is the SPOPS object alias, the value is a hashref
  of configuration information corresponding to that alias.

  In the absence of an 'alias_list', each of the SPOPS objects
  specified in the configuration will be processed.

alias_list (\@) (optional)
  List of aliases to process from the 'config'. Use this if for some
  reason you do not want to process all the aliases.

meta (\%) (optional)
  Can also be in the 'config' hashref -- see information under
  'parse_config()' below.

create_spops_class( \%config, \%spops_config )

Takes configuration information for a single SPOPS class, creates it on-the-fly and reads in any external code when specified.

Note that you can pass a true value for the key 'require_isa' in the \%config parameter. The routine will then try to 'require' every class in the 'isa' field of your SPOPS class configuration.

Returns: the class name if successful.

parse_config( \%config, \%spops_config )

Takes a hashref of configuration information and returns the classes created/configured properly.

One of the keys in the configuration is special. You can pass it in directly as a parameter (using the 'meta' key) or put it in the configuration (using the '_meta' key). If you do neither, the system will use a default (currently consisting of parsing the fields 'field', 'no_insert', 'no_update' and 'skip_undef' from an arrayref into a hashref.)

This 'meta' information allows you to manipulate the information in the configuration. Generally this is only for easier input: who wants to type out an entire hashref when all you want is to list some fields that get used later as lookups?

The 'meta' information is a hashref. Currently the only supported key is 'parse_into_hash', which takes a listref and makes it into a hashref to facilitate individual lookups. (No 'grep in a void context' for us!)

So we read in the \%spops_config information, massage it if necessary and assign the information to the SPOPS class configuration. After this class is run you should be able to call:

my \%class_config = $object_class->CONFIG;

And get back a hashref of configuration information for the class.

Returns: the class name if successful.

create_relationship

Currently this creates the 'has_a' relationship and installs the ruleset information in each class that asks for it.

See the writeup below under "Relationship Fields".

Returns: the class name if successful.

_read_code_class

Used internally to emulate some of what 'require' does to find a file with code and then reads the subroutines into another package.

Returns: arrayref of filenames that whose subroutines were read into the SPOPS object class.

CONFIGURATION FIELDS EXPLAINED

The configuration for a SPOPS class can be elaborate or minimal, depending on your needs.

Required Fields

class ($)

Name the class you want to create.

field (\@) (parsed into \%)

List the properties of the object. If you try to assign to a property that is not in the list, SPOPS::Tie will warn you and the assignment will be discarded. For instance:

# configuration
class => 'My::HipHop',
field => [ qw/ hip hop hooray / ],
...

# code
my $obj = My::HipHop->new;
$obj->{'boo-yah'} = "and he said";

will result in a warning.

isa (\@)

List the classes that your class inherits from. This can be a combination of SPOPS and other classes -- for instance, you might use SPOPS::DBI for serialization functinality but another class (My::FullTextIndex) to implement a ruleset for full-text indexing. (See SPOPS for more information on rulesets.)

id_field ($)

Name the field that will be used to uniquely identify an object. The type of field does not matter, but the fact that each value is unique does. You also cannot use an empty string (or undef, or 'NULL') as an identifier.

SPOPS does not currently deal with objects that use multiple fields to identify a record. (In database parlance, this is a "multiple field primary key".) To get around the restriction, you can simply add another field to the record and use it as a primary key. Instead of using the 'fetch' method to retrieve records, you can create a simple 'fetch_by_blah' that takes two fields instead of one. (Note: on the TO DO list for SPOPS is the ability to create a 'fetch_by_blah' method on-the-fly from configuration information.

Optional Fields

code_class ($)

Note: This is not optional if you wish to draw code from a class separate from the one you are creating.

When this class finds a 'code_class' value, it tries to find the class somewhere in @ISA. If it can find the class, it reads the file in and puts the subroutines into the class you are creating. For instance:

...
class      => 'My::Tofu',
code_class => 'Food::Tofu',
...

Will read the routines from 'Food::Tofu' and put them into the 'My::Tofu' namespace. (It will also currently put any lexical variables from the code class into your class, so be careful.)

no_security ($)

Set this to a true value if you do not want this class to use security. This overrides all other values -- even if you have SPOPS::Secure in the 'isa' of your class, security will not be checked if this value is true. Be careful!

no_insert (\@) (parsed into (\%)

Specify fields that should not be included when we first create a record.

no_update (\@) (parsed into (\%)

Specify fields whose values should never be changed when we update a record.

skip_undef (\@) (parsed into (\%)

Specify fields that are not included on either a create or update if they are not defined. (Note that 'undef' is a bit of a misnomer -- we do a simple perl 'truth' test to see if the field exists or not.)

alias (\@)

What other aliases do you want this class to be known under? SPOPS does not currently do anything with this, but implementations can.

display (\%)

How should this object be displayed? Currently, the hashref it points to must have at least one key 'url', to which SPOPS appends a query string to identify this object.

name (\&)

How can we find the name of an individual object? For instance, in a contact database, the name of a person object is the full name of the person.

Here we expect a code reference. It can do anything complicated you like, but more often than not it is just:

name => sub { return $_[0]->{my_name_field} }

Note: it is on the TO DO list for SPOPS to implement allowing a scalar which names the property to use for assigning a name to an object.

object_name ($)

What is the generic name for an object? For instance, 'Document', 'Link', 'Page', 'Food'.

as_string_order (\@) as_string_label (\%)

Every SPOPS object has a method 'as_string' as defined in SPOPS. However, this is a very blunt instrument as it basically just dumps out the properties of the object into a string without any nice labelling or control over order. The 'as_string_order' field allows you to list the fields you want included in the 'as_string' output along with their order, and 'as_string_label' allows you to assign a label to these fields.

creation_security (\%) (used by SPOPS::Secure)

See SPOPS::Secure for more information how this is used.

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) NOT NULL 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

has_a (\%)

Define a one-to-one relationship between objects. Currently, this means that an object contains one or more fields that contain the ID value of another object.

So the 'has_a' field of a configuration tells this class what these relationships are, and this class automatically builds the subroutines to make this happen.

Here is what you find in the 'has_a' field:

{ 
 SPOPS-tag => [ 'field_with_id_value', 'field_with_id_value' ],
}

If you have the normal (simple) case, you will have something like:

user => [ 'user_id' ]

Where the name of the 'field_with_id_value' matches up with the 'id_field' from the SPOPS class you are linking to. In this case, your alias will simply be the SPOPS-tag:

alias: 'user'

Which means you can call

my $user = $obj->user;

And get back a SPOPS object.

However, if you have two or more items -- or one item that is not the same name as the id_field -- identified by a single type but different ID fields, e.g.

user => [ 'created_by', 'fulfilled_by' ]

The alias created will be the id field followed by an underscore followed by the type; in this case:

alias: 'created_by_user'
alias: 'fulfilled_by_user'

Or:

my $create_user  = $obj->created_by_user;
my $fulfill_user = $obj->fulfilled_by_user;

(Note: We are currently considering a proposal to change 'SPOPS-alias' in the configuration field to 'SPOPS-class' so the configuration can be more flexible.)

fetch_by (\@)

Create a 'fetch_by_{fieldname}' routine that simply returns an arrayref of objects that match the value of a particular field.

links_to (\@)

(See SPOPS::Configure::DBI for information.)

TO DO

BUGS

COPYRIGHT

Copyright (c) 2000 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>