NAME

Bric::Biz::Asset::Business::Parts::Tile::Container - Container Element

VERSION

$LastChangedRevision$

DATE

$LastChangedDate: 2005-08-17 13:28:00 -0700 (Wed, 17 Aug 2005) $

SYNOPSIS

# Creation of Objects
my $container = Bric::Biz::Asset::Business::Parts::Tile::Container->new($init);
my $container = Bric::Biz::Asset::Business::Parts::Tile::Container->lookup({
  id => $id
});
my @containers = Bric::Biz::Asset::Business::Parts::Tile::Container->list($params);
my @ids = Bric::Biz::Asset::Business::Parts::Tile::Container->list_ids($params);

$container = $container->add_element(\@containers);
my @elements = $container->get_elements;
$container = $container->delete_elements(\@containers);
$container = $container->is_container;
$container = $container->reorder->(@new_order);

DESCRIPTION

This class contains the contents of container elements, also known as story type elements, media type elements, and container subelements. These objects can contain one or more subelements, and those subelements can be either data elements or other container elements. This class inherits from Bric::Biz::Asset::Business::Parts::Tile.

INTERFACE

Constructors

my $container = Bric::Biz::Asset::Business::Parts::Tile::Container->new($init)

Construct a new container element object. The supported initial attributes are:

object_type

A string identifying the type of document the new container element is associated with. It's value can be "story " or "media".

object_instance_id

The ID of the story or media document the new container element is associated with.

place

The order of this element relative to the other subelements of the parent element.

object_order

The order of this element relative to the other container elements based on the same Bric::Biz::AsetType object that are subelements of the parent element.

parent_id

The ID of the container element that is the parent of the new container element.

element

A Bric::Biz::AssetType object that defines the structure of this container element.

element_id

An ID for the Bric::Biz::AssetType object that defines the structure of this container element.

active

A boolean value indicating whether the container element is active or inactive.

Throws:

Object of type not allowed.

Side Effects: NONE.

Notes: NONE.

my $container = Bric::Biz::Asset::Business::Parts::Tile->lookup($params)

Looks up a container element in the database by its ID and returns it. The lookup parameters are:

id

The ID of the conainer element to lookup. Required.

object

A story or media document object with which the conainer element is associated. Required unless object_type is specified.

object_type

The type of document object with which the container element is associated. Must be either "media" or "story". Required unless object is specified.

Throws:

Missing required Parameter 'id'.
Missing required Parameter 'object_type' or 'object'.
Improper type of object passed to lookup.

Side Effects: NONE.

Notes: NONE.

my @containers = Bric::Biz::Assets::Parts::Tile::Container->list($param)

Searches for and returns a list or anonymous array of container element objects. The supported parameters that can be searched are:

object

A story or media object with which the container elements are associated. Required unless object_type is specified.

object_type

The type of document with which the container elements are associated. Required unless object is specified.

object_instance_id

The ID of a story or container object with wich the container elements are associated. Can only be used if object_type is also specified and object is not specified.

name

The name of the container elements. Since the SQL LIKE operator is used with this search parameter, SQL wildcards can be used.

key_name

The key name of the container elements. Since the SQL LIKE operator is used with this search parameter, SQL wildcards can be used.

parent_id

The ID of the container element that is the parent element of the container elements. Pass undef to this parameter to specify that the parent_id must be NULL.

element_id

The ID of the Bric::Biz::AssetType object that specifies the structure of the container elements.

active

A boolean value indicating whether the returned data elements are active or inactive.

Throws: NONE.

Side Effects: NONE.

Notes: NONE

Destructors

$container->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Public Class Methods

my @ids = Bric::Biz::Assets::Parts::Tile::Container->list_ids($param)

Returns a list or anonymous array of container element IDs. The search parameters are the same as for list().

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Instance Methods

See also Bric::Biz::Asset::Business::Parts::Tile, from which Bric::Biz::Asset::Business::Parts::Tile::Container inherits.

my $element_id = $container->get_element_id

Returns the ID of the Bric::Biz::AssetType object that defines the structure of this element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->set_element_id($element_id)

Sets the ID of the Bric::Biz::AssetType object that defines the structure of this element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $object_order = $container->get_object_order

Returns the order number for this object relative to other container elements based on the same Bric::Biz::AssetType object.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->set_object_order($object_order)

Sets the order number for this object relative to other container elements based on the same Bric::Biz::AssetType object.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $story_id = $container->get_related_instance_id

Returns the ID of a story related to this container element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->set_related_instance_id($story_id)

Sets the ID of a story related to this container element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $media_id = $container->get_related_media_id

Returns the ID of a media document related to this container element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->set_related_media_id($media_id)

Sets the ID of a media document related to this container element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->set_related_story($story)

Creates a relationship between the container element and a story document.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$story = $container->get_related_story

If a story is related to this container element, this method returns that story object.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->set_related_media($media)

Creates a relationship between the container element and a media document.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$media = $container->get_related_media

If a media document is related to this container element, this method returns that media object.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$obj = $container->get_element

Returns the Bric::Biz::AssetType object that defines the structure of this container element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$name = $container->get_element_name

An alias for $container->get_name.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$key_name = $container->get_element_key_name

An alias for $container->get_key_name.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my @data = $container->get_possible_data

Returns a list or anonymous array of the Bric::Biz::AssetType::Parts::Data objects that define the types of data elements that can be subelements of this container element. This list would exclude any data elements that can only be added as subelements to this container element once, and have already been added.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my @elements = $container->get_possible_containers

Returns a list or anonymous array of the Bric::Biz::AssetType::Parts::Data objects that define the types of data elements that can be subelements of this container element. This is synonymous with $container->get_element->get_containers, since containers do not support occurence constraints.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container = $container->add_data($atd, $value, $place);

Pass a Bric::Biz::AssetType::Parts::Data object and a value for a new data element, and that new data element will be added as a subelement of the container element. An optional third argument specifies the place for that data element in the order of subelements of this container element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$new_container = $container->add_container($element)

Adds a new container subelement to this container element. Pass in the required Bric::Biz::AssetType object specifying the structure of the new container subelement.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $data = $element->get_data_element($key_name, $obj_order)

Returns a specific data subelement of this container element. Pass in the key name of the data element to be retreived. By default, the first data element with that key name will be returned. Pass in an optional second argument to specify the object_order of the data element to be retrieved.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my @data = $container->get_data_elements
my @data = $element->get_data_elements;
@data = $element->get_data_elements(@key_names);

Returns a list or anonymous array of the data subelements of this element. If called with no arguments, it returns all of the data subelements. If passed a list of key names, the only the data subelements with those key names will be returned.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$string = $element->get_data($key_name, $obj_order)
$string = $element->get_data($key_name, $obj_order, $date_format)

Returns the value of a specific data subelement of this container element. Pass in the key name of the data element to be retreived. By default, the first data element with that key name will be returned. Pass in an optional second argument to specify the object_order of the data element to be retrieved. Pass in the optional $date_format argument if you expect the data returned from $key_name to be of the date type, and you'd like a format other than that set in the "Date Format" preference.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my $subelement = $container->get_container($key_name, $obj_order)

Returns a specific conainer subelement of this container element. Pass in the key name of the container element to be retreived. By default, the first container element with that key name will be returned. Pass in an optional second argument to specify the object_order of the container element to be retrieved.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my @containers = $container->get_containers
my @containers = $element->get_containers;
@containers = $element->get_containers(@key_names);

Returns a list or anonymous array of the container subelements of this container subelement. If called with no arguments, it returns all of the container subelements. If passed a list of key names, the only the container subelements with those key names will be returned.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my @subelements = $container->get_elements
my @subelements = $container->get_elements(@key_names)

Returns a list or anonymous array of all of the data and container subelements of this container subelement, in the order specified by their place attributes. If called with no arguments, it returns all of the subelements. If passed a list of key names, the only the subelements with those key names will be returned.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

my @elements = $container->get_tiles

An alias for get_elements(), provided for backwards compatability.

$container->add_element($subelement)

Adds an element to the current container element as a subelement. It will be given a place attribute and an object_order attribute relative to the other subelements of this container element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->add_tile($subelement)

An alias for add_element(), provided for backwards compatability.

$container->delete_tiles(\@subelements)

Removes the specified subelements from the current element. The arguments that can be passed via the array reference can be either container or data element objects or hash references with the following keys:

type

The type of element to be deleted. The value of this parameter must be either "data" or "container".

id

The ID of the element to be deleted.

Throws: NONE.

Side Effects: Will shift and reorder the remaining subelements to fit. So if telements with IDs of 2, 4, 7, 8, and 10 are contained and 4 and 8 are removed the new list of tiles will be 2, 7, and 10

Notes: Doesn't actually do any deletions, just schedules them. Call save() to complete the deletion.

$container->delete_tiles(\@subelements)

An alias for delete_elements(), provided for backwards compatability.

$container->prepare_clone

Prepares the conainer element to be cloned, such as when a new version of a document is created, or when a document itself is cloned.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->reorder_elements(\@subelements)

Pass in an array reference of subelements in the order they are to be placed relative to one another, and they will be reordered in that order.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->reorder_tiles(\@subelements)

An alias for reorder_elements(), provided for backwards compatability.

my $is_container $container->is_container;

Returns true, since container elements are, in fact, container elements.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->do_delete

Prepares this container element and its subelements to be removed.

Throws: NONE.

Side Effects: NONE.

Notes: NONE

$container->save

Saves the changes to the container element to the database.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

PRIVATE

Private Class Methods

Bric::Biz::Asset::Business::Parts::Tile::Container->_do_list($class, $param, $ids)

Called by list() or list_ids(), this method returns either a list of ids or a list of objects, depending on the third argument.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Private Instance Methods

$container->_do_delete

Called by save(), this method deletes the container element from the database.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->_select_container($param)

Called by lookup(), this method actually looks a container element up in the database.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->_do_insert()

Called by save(), this method inserts the container element into the database.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->_do_update

Called by save(), this method updates the container element into the database.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

$container->_sync_elements

Called by save() this method preforms all the operations on the subelements.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

NOTES

NONE

AUTHOR

"Michael Soderstrom" <miraso@pacbell.net> Bricolage Engineering

SEE ALSO

perl, Bric, Bric::Biz::Asset, Bric::Biz::Asset::Business, Bric::Biz::Asset::Business::Parts::Tile