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

$LastChangedRevision$

$LastChangedDate: 2005-07-10 21:05:35 -0700 (Sun, 10 Jul 2005) $

  # 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;

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.

$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. 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. Returns a list or anonymous array of Bric::Util::Grp objects. The supported keys in the CW$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 CWobj_id to have CWlist() return group objects with member objects representing a particular Bricolage object.

obj_id

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

parent_id

A group parent ID.

active

Pass in a true value to return only active groups (the default) or 0 to return only inactive groups. Pass CWundef 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.

description

A group description.

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.

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:

*

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 CWobj or CWobj_id & CWpackage 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();

$self->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY

Returns a list or anonymous array of Bric::Util::Grp IDs. The supported keys in the CW$params hash reference are the same as for the CWlist() method. 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 CWobj or CWobj_id & CWpackage 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. Returns a list or anonymous array of the supported classes in the group that can have their CWlist() 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 CWget_supported_classes in that some classes' CWlist() methods may inherit from others, and we don't want the same CWlist() 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 CWget_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 CWsecret parameter is passed to CWnew(). Throws: NONE. Side Effects: NONE. Notes: NONE. 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. Returns a Bric::Util::Class object describing this class. Throws: NONE. Side Effects: NONE. Notes: Uses Bric::Util::Class->lookup() internally. 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. 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 CW$grp_id. Throws: NONE. Side Effects: NONE. Notes: This method must be called from a subclass of Bric::Util::Grp. 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. 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.

Returns the database ID of the group object Throws: NONE. Side Effects: NONE. Notes: Returns CWundef if the ID the group is new and its CWsave() method has not yet been called. Returns the name of the group. Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the name of the group. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the description of the group. Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the description of the group. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the ID of this group's parent, and CWundef if this is the root group. Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the ID for the parent of this group. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the ID of Bric::Util::Class object representing the members of this group. Throws: NONE. Side Effects: NONE. Notes: NONE. 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. 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. Returns a list of all of this group's parent group IDs. Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the active flag for the object Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the active flag to inactive Throws:

*

Cannot deactivate permanent group. Side Effects: NONE. Notes: NONE. Returns self if the object is active undef otherwise Throws: NONE. Side Effects: NONE. Notes: NONE. 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 CWid parameter.

id

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

attrs

Attributes to be associated with the new member object.

no_check

If true, CWadd_member() will not check to see if the object being added to the group is already a member. Defaults to false. Either the CWobj parameter or both the CWpackage and CWid parameters are required. Throws:

*

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

*

Object not allowed in group. Side Effects: NONE. Notes: NONE. Convenience method that calls CW$grp->add_member on each in an array reference of new member object parameters. See CWadd_member() for documentation of the valid parameters. Throws:

*

Missing required parameters 'obj' or 'id' & 'package' Side Effects: NONE. Notes: NONE. Returns a list or a anonymous array of the member objects that are in the group. Throws: NONE. Side Effects: NONE. Notes: NONE. 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 CWget_list_classes() and calls CWlist() on each, passing in the required CWgrp_id parameter. Thus this method will not reflect any changes made to group membership unless CWsave() 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();

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 CWhas_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. 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 CWdelete_member() on every item in the array reference passed as the argument. Notes: NONE. 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 CW$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 CWpackage.

package

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

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 CWadd_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. Sets an individual attribute for the members of this group Throws: NONE. Side Effects: NONE. Notes: NONE. Deletes attributes that apply to members Throws: NONE. Side Effects: NONE. Notes: NONE. Takes a list of attributes and sets them to apply to the members Throws: NONE. Side Effects: NONE. Notes: NONE. Sets meta information on member attributes Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the member meta attributes Throws: NONE. Side Effects: NONE. Notes: NONE. Deletes the meta information for these attributes. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns all the attrs as a hashref for a given member subsystem Throws: NONE. Side Effects: NONE. Notes: NONE. Returns an individual attribute for given parameters Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the SQL type of an individual attribute. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns a hash of the attributes for a given subsys Throws: NONE. Side Effects: NONE. Notes: NONE. 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. 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. Sets a single attribute on this group Throws: NONE. Side Effects: NONE. Notes: NONE. Returns a single attribute that pretains to the group Throws: NONE. Side Effects: NONE. Notes: NONE. Deletes the attributes from the group Throws: NONE. Side Effects: NONE. Notes: NONE. 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. Sets meta information on group attributes Throws: NONE. Side Effects: NONE. Notes: NONE. Returns group meta information Throws: NONE. Side Effects: NONE. notes: NONE. deletes meta information that pretains to this here group. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns all of the group attrs as a hash ref Throws: NONE. Side Effects: NONE. Notes: NONE. Returns all the attributes and their meta information for the group subsys Throws: NONE. Side Effects: NONE. Notes: NONE. Updates the database to reflect the changes made to the object Throws: NONE. Side Effects: NONE. Notes: NONE.

NONE.

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. 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. 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. Deletes the attributes from this group and its members Throws: NONE. Side Effects: Deletes from all the members as well. Notes: NONE. Internal Method to return attributes from the object or the cache Throws: NONE. Side Effects: NONE. Notes: NONE. returns all attrs for a given subsystem Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the meta information for this group on the attr object or caches it for later storage Throws: NONE. Side Effects: NONE. Notes: NONE. Deletes the meta info from the group and possibly its members Throws: NONE. Side Effects: NONE. Notes: NONE. Returns stored meta information from the attr object or the attribute cache Throws: NONE. Side Effects: NONE. Notes: NONE. Will return the group that is this groups' parent if one has been defined Throws: NONE. Side Effects: NONE. Notes: NONE. Internal method that recursivly calls itself to determine all of its parents. Throws: NONE. Side Effects: NONE. Notes: NONE. Called from save it will do the insert for the grp object Throws: NONE. Side Effects: NONE. Notes: NONE. Called by the save method, this will update the record Throws: NONE. Side Effects: NONE. Notes: NONE. Internal method that stores the attributes and meta information from a save Throws: NONE. Side Effects: NONE. Notes: NONE.

Returns the results of a query for Bric::Util::Grp objects. The parameters supported by the CW$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 CWobj_id to have CW_do_list() return group objects with member objects representing a particular Bricolage object.

obj_id

A Bricolage object ID. Use in combination with CWpackage to have CW_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 CWobj or CWobj_id & CWpackage parameters are used, then this function must be called from a subclass.

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

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

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