Bric - The Bricolage base class.

Version

$LastChangedRevision$

Release Version

1.8.8

Date

$LastChangedDate: 2005-10-26 15:38:36 -0700 (Wed, 26 Oct 2005) $

Subversion ID

$Id: Bric.pm 6870 2005-10-26 22:38:36Z theory $

  use base qw(Bric);

The Bric class is an abstract class should never be used directly. Instead new classes should be derived from it.

new

  my $obj = Bric->new($init);

Call this constructor from all derived classes. This sets up some basic fields and methods.

Throws:

Exception::Gen

lookup

  my $obj = Bric->lookup({ id => $obj_id });

This method is similar to CWnew() except it is used only to retrieve a already existing object of this type from the database whereas CWnew() creates a new, empty object. All subclasses should override this method in order to look up their objects in the database. However, they must first call CWcache_lookup() to see if it can retrieve the object from the cache. If they can, they should simply return the object. Otherwise, once they look up the object in the database, they should cache it via the CWcache_me() method. For example:

  sub lookup {
      my $pkg = shift;
      my $self = $pkg->cache_lookup(@_);
      return $self if $self;
      # ... Continue to look up object in the database. Then...
      $self->cache_me;
  }

Throws:

Exception::MNI

cache_lookup

  my $obj = Bric->cache_lookup({ id => $obj_id });

Looks up an object in the cache and returns it if it exists. Otherwise it returns CWundef. This method is meant to be used by Bric subclasses in their CWlookup() methods. See CWlookup() for an example.

list

  my @objs = Bric->list($params);
  my $objs_aref = Bric->list($params);

This is an abstract method. All derived classes should override this method. It takes a list of parameters and searches the database for objects that meet the parameter serach criteria. It returns a list of objects in an array context, and an array reference of objects in a scalar context. In the concrete implementations of this method, classes should also call CWcache_me() for every object to be returned.

Throws:

Exception::MNI

list_ids

  my @ids = Bric->list_ids($params);
  my $ids_aref = Bric->list_ids($params);

This is an abstract method. It takes a list of parameters and searches the database for objects that meet the parameter serach criteria. It returns a list of object IDs in an array context, and an array reference of object IDs in a scalar context.

Throws:

Exception::MNI

my_meths

  my $meths = Bric->my_meths
  my @meths = Bric->my_meths(1);
  my $meths_aref = Bric->my_meths(1);
  @meths = Bric->my_meths(0, 1);
  $meths_aref = Bric->my_meths(0, 1);

Returns an anonymous hash of introspection data for this object. If called with a true argument, it will return an ordered list or anonymous array of introspection data. If a second true argument is passed instead of a first, then a list or anonymous array of introspection data will be returned for properties that uniquely identify an object (excluding CWid, which is assumed).

Each hash key is the name of a property or attribute of the object. See each subclass for a list of the properties included in the hash. The value for a hash key is another anonymous hash containing the following keys:

name

The name of the property or attribute. Is the same as the hash key when an anonymous hash is returned.

disp

The display name of the property or attribute.

get_meth

A reference to the method that will retrieve the value of the property or attribute.

get_args

An anonymous array of arguments to pass to a call to get_meth in order to retrieve the value of the property or attribute.

set_meth

A reference to the method that will set the value of the property or attribute.

set_args

An anonymous array of arguments to pass to a call to set_meth in order to set the value of the property or attribute.

type

The type of value the property or attribute contains. There are only three types:

short

date

blob

len

If the value is a 'short' value, this hash key contains the length of the field.

search

The property is searchable via the list() and list_ids() methods.

req

The property or attribute is required.

props

An anonymous hash of properties used to display the property or attribute. Possible keys include:

type

The display field type. Possible values are

text

textarea

password

hidden

radio

checkbox

select

length

The Length, in letters, to display a text or password field.

maxlength

The maximum length of the property or value - usually defined by the SQL DDL.

rows

The number of rows to format in a textarea field.

cols

The number of columns to format in a textarea field.

vals

An anonymous hash of key/value pairs reprsenting the values and display names to use in a select list.

Notes: The method is a no-op here in the Bric base class. See the subclasses for implementations and detail regarding the properties they return.

get/set

 my $val = $obj->get_field1;
 $obj = $obj->set_field1($val);

This is the AUTOLOAD handler. It translates all set and get operations into subroutines acting upon the fields in derived classes.

Side Effects: Creates a custom subroutine reference in the object package's namespace.

Throws:

Exception::GEN

get_grp_ids

  my @grp_ids = $obj->get_grp_ids;
  my $grp_ids_aref = $obj->get_grp_ids;
  my @grp_ids = Bric->get_grp_ids;
  my $grp_ids_aref = Bric->get_grp_ids;

Return a list of IDs for the Bric::Util::Grp objects to which the object belongs. When called as a class method, return the value of the class' CWINSTANCE_GROUP_ID constant. Values are returned as a list in an array context, and as an array reference in a scalar context.

cache_me

  $obj = $obj->cache_me;

Caches the object for later retrieval by the CWlookup() class method. Should be called for all objects retrieved from the database, including all objects to be returned by CWlookup(), CWlist(), and CWhref() methods.

uncache_me

  $obj->uncache_me;

Remove an object from the cache. This should be done before an object's associated data is permanently deleted from the database.

register_instance

  $obj = $obj->register_instance;

Add the current object to the appropriate All group in the database. These are groups that contain every instance of a particular type of object.

Throws:

Exception::DA

unregister_instance

  $obj = $obj->unregister_instance;

Remove the current object from the appropriate All group in the database. These are groups that contain every instance of a particular type of object.

Throws:

Exception::DA

save

  $obj = $obj->save;

Save the current object by setting an internal flag indicating that it has been saved. Subclasses should override this method to save object data to the database.

register_fields

  Bric::register_fields({ field1  => Bric::FIELD_READ,
                          field2  => Bric::FIELD::RDWR
                        });

This function is used by sub classes to register their field names and assign access levels to them.

Side Effects: Defines a subroutine named CWACCESS() in the caller's package.

Throws:

Exception::GEN

Garth Webb <garth@perijove.com>

Sam Tregar <stregar@about-inc.com>

NONE