Name

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

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->is_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_objs = $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
permanent
secret

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. May use ANY for a list of possible values, but objects just all be of the same class.

package

A Bricolage class name. Use in combination with obj_id to have 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 list() return group objects with member objects representing a particular Bricolage object. May use ANY for a list of possible values.

parent_id

A group parent ID. May use ANY for a list of possible values.

active

Pass in a true value to return only active groups (the default) or 0 to return only inactive groups. Pass undef to get a list of active and inactive groups.

inactive

Inactive groups will be returned if this parameter is true.

secret

Pass in a true value to return only secret groups. False by default.

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. May use ANY for a list of possible values.

description

A group description. May use ANY for a list of possible values.

permananent

A boolean to return permanent or non-permanent groups.

grp_id

A Bric::Util::Grp::Grp group ID. All groups that are members of the corresponding Bric::Util::Grp::Grp object will be returned. May use ANY for a list of possible values.

Order

A property name to order by.

OrderDirection

The direction in which to order the records, either "ASC" for ascending (the default) or "DESC" for descending.

Throws:

Side Effects: NONE.

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

Also, the Grp subclasses aren't loaded by this class, so when using the Bric API outside of Bricolage, you need to require the object class on the fly; for example:

use Bric::Util::Grp::Grp;
my $supported = Bric::Util::Grp::Grp->get_supported_classes();
foreach my $grpclass (keys %$supported) {
    eval "require $grpclass";
}
my $grps = Bric::Util::Grp->list();

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:

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.

my @list_classes = Bric::Util::Grp->get_list_classes

Returns a list or anonymous array of the supported classes in the group that can have their list() methods called in succession to assemble a list of member objects. This data varies from that stored in the keys in the hash reference returned by get_supported_classes in that some classes' list() methods may inherit from others, and we don't want the same list() method executed more than once. A good example of such a case is the various Media subclasses managed by Bric::Util::Grp::Asset.

Throws: NONE.

Side Effects: This method is used internally by get_objects().

Notes:

Subclasses should override this method.

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

Returns true if by default groups of this class are not available for end user management. Secret groups are used by Bricolage only for internal purposes. This class method sets the default value for new group objects, unless a secret parameter is passed to new().

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:

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)
my (@meths || $meths_aref) = Bric::Util::Grp->my_meths(0, TRUE)

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. 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->is_secret

Returns true if the group is a secret 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:

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:

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:

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. Only returns object if the group object has been saved and has an ID.

Throws: NONE.

Side Effects: NONE.

Notes: This method gets a list of classes from get_list_classes() and calls list() on each, passing in the required grp_id parameter. Thus this method will not reflect any changes made to group membership unless save() has been called on the group object.

Also, the object class isn't loaded by the group class, so when using the Bric API outside of Bricolage, you need to require the object class on the fly; for example:

foreach my $c ($grp->get_list_classes()) {
    eval "require $c";
}
my $objs = $grp->get_objects();
$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:

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:

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.

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

Returns the SQL type of an individual attribute.

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

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:

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 cannot 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. See the documentation for the list() method for a list of the supported parameters.

Throws:

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@justatheory.com>.

See Also:

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