Bric::Biz::Asset::Business::Parts::Tile::Container(3)

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

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2004-11-08 12:01:36 -0800 (Mon, 08 Nov 2004) $

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