• NAME
• VERSION
• DATE
• SYNOPSIS
• DESCRIPTION
• INTERFACE
  • Constructors
  • Destructors
  • Public Class Methods
  • Public Instance Methods
• PRIVATE
  • Private Class Methods
  • Private Instance Methods
  • Private Functions
• NOTES
• AUTHOR
• SEE ALSO:
• POD ERRORS

NAME

Bric::Util::Grp - A class for associating Bricolage objects

VERSION

$Revision: 1.16.2.4 $

DATE

$Date: 2002/10/23 19:03:33 $

SYNOPSIS

# Constructors.
my $grp = Bric::Util::Grp->new($init);
$grp = Bric::Util::Grp->lookup({ id => $id });
my @grps = Bric::Util::Grp->list($params);

# Class methods.
my @grp_ids = Bric::Util::Grp->list_ids($params)
my $class_id = Bric::Util::Grp->get_class_id;
my $supported_classes = Bric::Util::Grp->get_supported_classes;
my $class_keys_href = Bric::Util::Grp->href_grp_class_keys;
my $secret = Bric::Util::Grp->get_secret;
my $class = Bric::Util::Grp->my_class;
my $member_class = Bric::Util::Grp->member_class;
my $obj_class_id = Bric::Util::Grp->get_object_class_id;
my @member_ids = Bric::Util::Grp->get_member_ids($grp_id);
my $meths = Bric::Util::Grp->my_meths;

# Instance methods.
$id = $grp->get_id;
my $name = $grp->get_name;
$grp = $grp->set_name($name)
my $desc = $grp->get_description;
$grp = $grp->set_description($desc);
my $parent_id = $grp->get_parent_id;
$grp = $grp->set_parent_id($parent_id);
my $class_id = $grp->get_class_id;
my $perm = $grp->get_permanent;
my $secret = $grp->get_secret;
my @parent_ids = $grp->get_all_parent_ids;

$grp = $grp->activate;
$grp = $grp->deactivate;
$grp = $grp->is_active;

# Instance methods for managing members.
my @members = $grp->get_members;
my @member_obss = $grp->get_objects;
$grp->add_member(\%member_spec);
$grp->add_members(\@member_specs);
$grp = $grp->delete_member(\%member_spec);
$grp = $grp->delete_members(\@member_specs);
my $member = $grp->has_member({ obj => $obj });

# Instance methods for managing member attributes.
$grp = $grp->set_member_attr($params);
$grp = $grp->delete_member_attr($params);
$grp = $grp->set_member_attrs(\@attr_specs);
$grp = $grp->set_member_meta($params);
my $meta = $grp->get_member_meta($params);
$grp = $grp->delete_member_meta($params);
my $attrs = $grp->all_for_member_subsys($subsys)
my $attr = $grp->get_member_attr($params);
my $attr_href = $grp->get_member_attr_hash($params);
my @attrs = $grp->get_member_attrs(\@params);

# Instance methods for managing group attributes.
@attrs = $grp->get_group_attrs(\@params);
$grp = $grp->set_group_attr($params);
$attr = $grp->get_group_attr($params);
$grp = $grp->delete_group_attr($params);
$grp = $grp->set_group_attrs(\@params);
$grp = $grp->set_group_meta($meta)
$meta = $grp->get_group_meta($params);
$grp = $grp->set_group_meta($params);
$grp = $grp->delete_group_meta($params);
$attr_href = $grp->get_group_attr_hash;
$attrs = $grp->all_for_group_subsys($subsys);

# Save the changes to the database
$grp = $grp->save;

DESCRIPTION

Grp is a class that associates Bricolages objects. Attributes can be assigned to the group as a whole, or to the members of the group. In the latter case, the attribute values may be changed for individual members.

INTERFACE

Constructors

$grp = Bric::Util::Grp->new($init)

This will create a new group object with optional initial state.

Supported Keys:

name

description

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = Bric::Util::Grp->lookup({ id => $id })

This will lookup an existing group based on the given ID.

Throws: NONE.

Side Effects: NONE.

Notes:

If COLS var changes index of class ID must change.

my (@grps || $grps_aref) = Bric::Util::Grp->list($params);

Returns a list or anonymous array of Bric::Util::Grp objects. The supported keys in the $params hash reference are:

obj

A Bricolage object. The groups returned will have member objects for this object.

package

A Bricolage class name. Use in combination with obj_id to have _do_list() return group objects with member objects representing a particular Bricolage object.

obj_id

A Bricolage object ID. Use in combination with package to have _do_list() return group objects with member objects representing a particular Bricolage object.

parent_id

A group parent ID.

inactive

Inactive groups will be returned if this parameter is true. Otherwise, only active groups will be returned.

all

Both secret and non-secret groups will be returned if this parameter is true. Otherwise only non-secret groups will be returned.

name

The name of a group.

permananent

A boolean to return permanent or non-permanent groups.

Throws:

• Unable to connect to database.

• Unable to prepare SQL statement.

• Unable to connect to database.

• Unable to select column into arrayref.

• Unable to execute SQL statement.

• Unable to bind to columns to statement handle.

• Unable to fetch row from statement handle.

Side Effects: NONE.

Notes: If the obj or obj_id & package parameters are used, then this method must be called from a subclass.

Destructors

$self->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY

Public Class Methods

my (@grp_ids || $grp_ids_aref) = Bric::Util::Grp->list_ids($params);

Returns a list or anonymous array of Bric::Util::Grp IDs. The supported keys in the $params hash reference are the same as for the list() method.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

obj

A Bricolage object. The groups returned will have member objects for this object.

package

A Bricolage class name. Use in combination with obj_id to have _do_list() return group objects with member objects representing a particular Bricolage object.

obj_id

A Bricolage object ID. Use in combination with package to have _do_list() return group objects with member objects representing a particular Bricolage object.

parent_id

A group parent ID.

inactive

Inactive groups will be returned if this parameter is true. Otherwise, only active groups will be returned.

all

Both secret and non-secret groups will be returned if this parameter is true. Otherwise only non-secret groups will be returned.

name

The name of a group.

permananent

A boolean to return permanent or non-permanent groups.

Throws:

• Unable to connect to database.

• Unable to prepare SQL statement.

• Unable to connect to database.

• Unable to select column into arrayref.

• Unable to execute SQL statement.

• Unable to bind to columns to statement handle.

• Unable to fetch row from statement handle.

Side Effects: NONE.

Notes: If the obj or obj_id & package parameters are used, then this method must be called from a subclass.

$class_id = Bric::Util::Grp->get_class_id

Returns the class ID representing the Bricolage class that this group is associated with.

Throws: NONE.

Side Effects: NONE.

Notes:

Subclasses should override this method.

$supported_classes = Bric::Util::Grp->get_supported_classes

Returns a hash reference of the supported classes in the group as keys with the short name as a value. The short name is used to construct the member table names and the foreign key in the table.

Throws: NONE.

Side Effects: NONE.

Notes:

Subclasses should override this method.

(1 || undef) = Bric::Util::Grp->get_secret

Returns true if this Grp class is not available for end user management. Secret groups are used by Bricolage only for internal purposes.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my (%class_keys || $class_keys_href) = Bric::Util::Grp->href_grp_class_keys

my (%class_keys || $class_keys_href) = Bric::Util::Grp->href_grp_class_keys(1)

Returns an anonymous hash representing the subclasses of Bric::Util::Grp. The hash keys are the key_names of those classes, and the hash values are their plural display names. By default, it will return only those classes whose group instances are not secret. To get all group subclasses, pass in a true value.

Throws:

• Unable to prepare SQL statement.

• Unable to connect to database.

• Unable to execute SQL statement.

• Unable to bind to columns to statement handle.

• Unable to fetch row from statement handle.

Side Effects: NONE.

Notes: NONE.

my $class = Bric::Util::Grp->my_class

Returns a Bric::Util::Class object describing this class.

Throws: NONE.

Side Effects: NONE.

Notes: Uses Bric::Util::Class->lookup() internally.

my $class = Bric::Util::Grp->member_class

Returns a Bric::Util::Class object describing the members of this group.

Throws: NONE.

Side Effects: NONE.

Notes: Uses Bric::Util::Class->lookup() internally.

$obj_class_id = Bric::Util::Grp->get_object_class_id;

If this method returns a value, then all members of the group will be assumed to be a member of the class for which the value is the ID.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

($member_ids || @member_ids) = Bric::Util::Grp->get_member_ids($grp_id)

Returns a list of the IDs representing the objects underlying the Bric::Util::Grp::Parts::Member objects that are members of the grp represented by $grp_id.

Throws: NONE.

Side Effects: NONE.

Notes: This method must be called from a subclass of Bric::Util::Grp.

my $meths = Bric::Util::Grp->my_meths

my (@meths || $meths_aref) = Bric::Util::Grp->my_meths(TRUE)

Returns an anonymous hash of instrospection data for this object. If called with a true argument, it will return an ordered list or anonymous array of intrspection data. The format for each introspection item introspection is as follows:

Each hash key is the name of a property or attribute of the object. 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.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Instance Methods

$id = $grp->get_id

Returns the database ID of the group object

Throws: NONE.

Side Effects: NONE.

Notes:

Returns undef if the ID the group is new and its save() method has not yet been called.

my $name = $grp->get_name

Returns the name of the group.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->set_name($name)

Sets the name of the group.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $desc = $grp->get_description

Returns the description of the group.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->set_description($desc)

Sets the description of the group.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $parent_id = $grp->get_parent_id

Returns the ID of this group's parent, and undef if this is the root group.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->set_parent_id($parent_id)

Sets the ID for the parent of this group.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $class_id = $grp->get_class_id

Returns the ID of Bric::Util::Class object representing the members of this group.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $perm = $grp->get_permanent

Returns true if the group is permanent, and false if it's not. Permanant groups cannot be deleted.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $secret = $grp->get_secret

Returns true if the group is a secrete group, and false if it's not. Secret groups are used internally by the API, and are not designed to be managed by users via the UI.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my (@pids || $pids_aref) = $grp->get_all_parent_ids

Returns a list of all of this group's parent group IDs.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->activate

Sets the active flag for the object

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->deactivate

Sets the active flag to inactive

Throws:

• Cannot deactivate permanent group.

Side Effects: NONE.

Notes: NONE.

($grp || undef) = $grp->is_active

Returns self if the object is active undef otherwise

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $member = $grp->add_member({ obj => $obj, attr => $attributes });

Adds an object to the group. The supported parameters are:

obj

The object to be added as a member of the group.

package

The package name of the class to which the object to be added as a member of the group belongs. Use in combination with the id parameter.

id

The ID of the object to be added as a member of the group. Use in combination with the package parameter.

attrs

Attributes to be associated with the new member object.

no_check

If true, add_member() will not check to see if the object being added to the group is already a member. Defaults to false.

Either the obj parameter or both the package and id parameters are required.

Throws:

• Missing required parameters 'obj' or 'id' & 'package'

• Object not allowed in group.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->add_members(\@member_params);

Convenience method that calls $grp->add_member on each in an array reference of new member object parameters. See add_member() for documentation of the valid parameters.

Throws:

• Missing required parameters 'obj' or 'id' & 'package'

Side Effects: NONE.

Notes: NONE.

(@members || $member_aref) = $grp->get_members

Returns a list or a anonymous array of the member objects that are in the group.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my (@objs || $objs_aref) = $grp->get_objects

Returns a list or anonymous arry of all of the Bricolage objects underlying the member objects in the group.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->delete_member($member);

$grp = $grp->delete_member($object);

$grp = $grp->delete_member($param);

Removes a member object from the group. If the argument to this method is a Bric::Util::Grp::Parts::Member object, then that object will be removed from the group. If the argument to this method is any other Bricolage object, the member object representing that object will be constructed and removed from this group. If the argument to this method is a hash reference, the supported parameter are the same as for the has_member() method.

Throws:

• Parameters 'id' and/or 'package' not passed to delete_member().

Side Effects:

Will delete members for the database ( ie. not make them inactive)

<Notes:> NONE.

$grp = $grp->delete_members($members);

Convenience method that takes a reference to an array of objects or their unique identifiers and removes them from the group.

Throws:

• Parameters 'id' and/or 'package' not passed to delete_member().

Side Effects: Calls delete_member() on every item in the array reference passed as the argument.

Notes: NONE.

($member || undef) = $grp->has_member($params);

Returns a Bric::Util::Grp::Parts::Member object representing the membership in the group of a Bricolage object if the object is a member, and undef if it's not a member. The $params hash reference accepts the following keys:

obj

The object that may be a member of the group.

id

The ID of the object that may be a member of the group. Use in combination with package.

package

The class package name of the object that may be a member of the group. Use in combination with id.

attr

An attribute of the member object. The member object will only be returned if it contains this attribute. Optional.

Throws: NONE.

Side Effects: NONE.

Notes: This method may return false if a member has been added via add_member() but the Grp object hasn't been saved. The upshot is that one should always call has_member() on a fully saved Grp object.

$grp = $grp->set_member_attr($params)

Sets an individual attribute for the members of this group

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->delete_member_attr($params)

Deletes attributes that apply to members

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->set_member_attrs( [ { name => $name, subsys => $subsys, value => $value, sql_type =>$sql_type, new => 1 } ] )

Takes a list of attributes and sets them to apply to the members

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->set_member_meta($params)

Sets meta information on member attributes

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$meta = $grp->get_member_meta($params)

Returns the member meta attributes

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->delete_member_meta($params)

Deletes the meta information for these attributes.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$attrs = $grp->all_for_member_subsys($subsys)

Returns all the attrs as a hashref for a given member subsystem

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$attr = $grp->get_member_attr($params)

Returns an individual attribute for given parameters

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$hash = $grp->get_member_attr_hash($params)

Returns a hash of the attributes for a given subsys

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

(@vals || $val_aref) = $grp->get_member_attrs(\@params)

Retrieves the value of the attribute that has been assigned as a default for members that has the given name and subsystem

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

(@vals || $val_aref) = $grp->get_group_attrs(\@params)

Get attributes that describe the group but do not apply to members. This retrieves the value in the attribute object from a special subsystem which contains these. This will be returned as a list of values

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->set_group_attr($params)

Sets a single attribute on this group

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$attr = $grp->get_group_attr($params)

Returns a single attribute that pretains to the group

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->delete_group_attr

Deletes the attributes from the group

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->set_group_attrs(\@params)

Sets attributes that describe the group but do not apply to members. This sets the value in the attribute object to a special subsystem which contains these

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->set_group_meta($meta)

Sets meta information on group attributes

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$meta = $grp->get_group_meta($params)

Returns group meta information

Throws: NONE.

Side Effects: NONE.

notes: NONE.

$grp = $grp->delete_group_meta($params)

deletes meta information that pretains to this here group.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$attr_hash = $grp->get_group_attr_hash

Returns all of the group attrs as a hash ref

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$attrs = $grp->all_for_group_subsys

Returns all the attributes and their meta information for the group subsys

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->save

Updates the database to reflect the changes made to the object

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

PRIVATE

Private Class Methods

NONE.

Private Instance Methods

$ret = _select_group( $where, [$bind] )

takes the where clause and the bind vars and preforms the query

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $memb_coll = $get_memb_coll->($self)

Returns the collection of members for this group. The collection is a Bric::Util::Coll::Member object. See that class and its parent, Bric::Util::Coll, for interface details.

Throws:

• Bric::_get() - Problems retrieving fields.

• Unable to prepare SQL statement.

• Unable to connect to database.

• Unable to select column into arrayref.

• Unable to execute SQL statement.

• Unable to bind to columns to statement handle.

• Unable to fetch row from statement handle.

• Incorrect number of args to Bric::_set().

• Bric::set() - Problems setting fields.

Side Effects: NONE.

Notes: NONE.

$attribute_obj = $self->_get_attribute_obj

Will return the attribute object. Methods that need it should check to see if they have it and if not then get it from here. If there is an ID defined then it will look up based on it otherwise it will create a new one.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$self = $self->_set_attr($param)

Internal method which either sets the attribute upon the attribute object, or if we can not get one yet into a cached area.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$self = $self->_delete_attr($param)

Deletes the attributes from this group and its members

Throws: NONE.

Side Effects: Deletes from all the members as well.

Notes: NONE.

$attr = $self->_get_attr( $param )

Internal Method to return attributes from the object or the cache

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$attrs = $self->_get_attr_hash( $param, $parent)

returns all attrs for a given subsystem

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$self = $self->_set_meta( $param )

Sets the meta information for this group on the attr object or caches it for later storage

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$self = $self->_delete_meta( $param, $mem);

Deletes the meta info from the group and possibly its members

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$meta = $self->_get_meta( $param )

Returns stored meta information from the attr object or the attribute cache

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$parent_obj = $self->_get_parent_object

Will return the group that is this groups' parent if one has been defined

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $pids_aref = $self->_get_all_parent_ids

Internal method that recursivly calls itself to determine all of its parents.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$grp = $grp->_do_insert

Called from save it will do the insert for the grp object

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$self = $self->_do_update

Called by the save method, this will update the record

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$self = $self->_sync_attributes

Internal method that stores the attributes and meta information from a save

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Private Functions

my (@grps || $grps_aref) = _do_list($params);

my (@grp_ids || $grp_ids_aref) = _do_list($params, 1);

Returns the results of a query for Bric::Util::Grp objects. The parameters supported by the $params hash reference are:

obj

A Bricolage object. The groups returned will have member objects for this object.

package

A Bricolage class name. Use in combination with obj_id to have _do_list() return group objects with member objects representing a particular Bricolage object.

obj_id

A Bricolage object ID. Use in combination with package to have _do_list() return group objects with member objects representing a particular Bricolage object.

parent_id

A group parent ID.

inactive

Inactive groups will be returned if this parameter is true. Otherwise, only active groups will be returned.

all

Both secret and non-secret groups will be returned if this parameter is true. Otherwise only non-secret groups will be returned.

name

The name of a group.

permananent

A boolean to return permanent or non-permanent groups.

Throws:

• Unable to connect to database.

• Unable to prepare SQL statement.

• Unable to connect to database.

• Unable to select column into arrayref.

• Unable to execute SQL statement.

• Unable to bind to columns to statement handle.

• Unable to fetch row from statement handle.

Side Effects: NONE.

Notes: If the obj or obj_id & package parameters are used, then this function must be called from a subclass.

NOTES

Need to add parentage info and a possible method to list children and maybe their children and so on as well

AUTHOR

Michael Soderstrom <miraso@pacbell.net>. Member management and documentation by David Wheeler <david@wheeler.net>.

SEE ALSO:

Bric.pm, Bric::Util::Grp::Parts::Member

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 393:

'=item' outside of any '=over'

Around line 406:

You forgot a '=back' before '=head2'

Around line 811:

Expected '=item *'

Around line 813:

Expected '=item *'

Around line 815:

Expected '=item *'

Around line 817:

Expected '=item *'

Around line 819:

Expected '=item *'

Around line 821:

Expected '=item *'

Around line 823:

Expected '=item *'

Around line 951:

'=item' outside of any '=over'

Around line 2064:

You forgot a '=back' before '=head1'

Around line 2076:

'=item' outside of any '=over'

Around line 2725:

You forgot a '=back' before '=head2'