Bric(3p)              User Contributed Perl Documentation             Bric(3p)



NAME
       Bric - The Bricolage base class.

VITALS
       Version
           $LastChangedRevision$

       Release Version
           1.10.3

       Date
           $LastChangedDate: 2006-06-23 04:56:33 +0200 (Fri, 23 Jun 2006) $

       Subversion ID
           $Id: Bric.pm 7605 2006-06-23 02:56:33Z theory $

SYNOPSIS
         use base qw(Bric);

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

INTERFACE
   Constructors
       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 "new()" except it is used only to retrieve a
       already existing object of this type from the database whereas "new()"
       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 "cache_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 "cache_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 "undef". This method is meant to be used by Bric subclasses
       in their "lookup()" methods. See "lookup()" 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 "cache_me()" for every object to be returned.

       Throws:

       Exception::MNI

   Class Methods
       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 "id", 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.

   Instance Methods
       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' "INSTANCE_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 "lookup()" class method.
       Should be called for all objects retrieved from the database, including
       all objects to be returned by "lookup()", "list()", and "href()"
       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.

   Functions
       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 "ACCESS()" in the caller's
       package.

       Throws:

       Exception::GEN

AUTHOR
       Garth Webb <garth@perijove.com>

       Sam Tregar <stregar@about-inc.com>

SEE ALSO
       NONE



perl v5.12.2                      2006-06-22                          Bric(3p)
