Bric::Biz::Element::Container(3)

NAME
Bric::Biz::Element::Container - Container Element

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2007-09-10 10:15:05 +0200 (Mon, 10 Sep 2007) $

SYNOPSIS
  # Creation of Objects
  my $container = Bric::Biz::Element::Container->new($init);
  my $container = Bric::Biz::Element::Container->lookup({
    id => $id
  });
  my @containers = Bric::Biz::Element::Container->list($params);
  my @ids = Bric::Biz::Element::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::Element.

INTERFACE

  Constructors

my $container = Bric::Biz::Element::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::ElementType object that defines the structure of this container element.

    element_type_id
        An ID for the Bric::Biz::ElementType 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::Element->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::Element::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. May use "ANY" for a list of possible values.

    name
        The name of the container elements. Since the SQL "LIKE" operator is used with this search parameter, SQL wildcards can be used. May use "ANY" for a list of possible values.

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

    description
        The description of the container elements. Since the SQL "LIKE" operator is used with this search parameter, SQL wildcards can be used. May use "ANY" for a list of possible values.

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

    element_type_id
        The ID of the Bric::Biz::ElementType object that specifies the structure of the container elements. May use "ANY" for a list of possible values.

    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::Element::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::Element, from which Bric::Biz::Element::Container inherits.

my $element_type_id = $container->get_element_type_id
    Returns the ID of the Bric::Biz::ElementType object that defines the structure of this element.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$container->set_element_type_id($element_type_id)
    Sets the ID of the Bric::Biz::ElementType object that defines the structure of this element.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

my $bool = $container->can_relate_story
    Returns a true value if the container is allowed to have a related story, and false if it is not.

my $bool = $container->can_relate_media
    Returns a true value if the container is allowed to have a related media document, and false if it is not.

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::ElementType 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::ElementType object.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

my $story_id = $container->get_related_story_id
my $story_id = $container->get_related_instance_id
    Returns the ID of a story related to this container element. "get_related_instance_id()" is provided for backwards compatability with versions of Bricolage prior to 1.9.1.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$container->set_related_story_id($story_id)
$container->set_related_instance_id($story_id)
    Sets the ID of a story related to this container element. "set_related_instance_id()" is provided for backwards compatability with versions of Bricolage prior to 1.9.1.

    Throws:

    Element cannot have a related story

    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:

    Element cannot have a related media

    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_type
    Returns the Bric::Biz::ElementType object that defines the structure of this container element.

    Throws: NONE.

    Side Effects: NONE.

    Notes: "get_element()" has been deprecated in favor of this method.

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

$container->get_possible_field_types()
$container->get_possible_data()
      my @field_types = $container->get_possible_field_types();
         @field_types = $container->get_possible_data();

    Returns a list or anonymous array of the Bric::Biz::ElementType::Parts::FieldType 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: "get_possible_data()" is the deprecated form of this method.

my @elements = $container->get_possible_containers
    Returns a list or anonymous array of the Bric::Biz::ElementType::Parts::FieldType objects that define the types of data elements that can be subelements of this container element. This is synonymous with "$container->get_element_type->get_containers", since containers do not support occurence constraints.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$container->add_field($field_type, $value, $place);
$container->add_data($field_type, $value, $place);
    Pass a Bric::Biz::ElementType::Parts::FieldType object and a value for a new field element, and that new field element will be created and added as a subelement of the container element. An optional third argument specifies the "place" for that field element in the order of subelements of this container element.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$new_container = $container->add_container($element_type)
    Adds a new container subelement to this container element. Pass in the required element type (Bric::Biz::ElementType) object specifying the structure of the new container subelement.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

my $field = $element->get_field($key_name, $obj_order)
my $field = $element->get_data_element($key_name, $obj_order)
    Returns a specific field subelement of this container element. Pass in the key name of the field to be retreived. By default, the first field with that key name will be returned. Pass in an optional second argument to specify the "object_order" of the field to be retrieved.

    Throws: NONE.

    Side Effects: NONE.

    Notes: "get_data_element()" is the deprecated form of this method.

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

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

    Throws: NONE.

    Side Effects: NONE.

    Notes: "get_data_elements()" is the deprecated form of this method.

$value = $element->get_value($key_name, $obj_order)
$value = $element->get_value($key_name, $obj_order, $date_format)
$value = $element->get_data($key_name, $obj_order)
$value = $element->get_data($key_name, $obj_order, $date_format)
    Returns the value of a specific field subelement of this container element. Pass in the key name of the field element to be retreived. By default, the first field element with that key name will be returned. Pass in an optional second argument to specify the "object_order" of the field element to be retrieved. Pass in the optional $date_format argument if you expect the value 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: "get_data()" is the deprecated form of this method.

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_elements(\@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 elements 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.

my $pod = $container->serialize_to_pod;
my $pod = $container->serialize_to_pod($field_key_name);
    Serializes the element and all of its subelements into the pseudo-pod format parsable by "update_from_pod()". Pass in a field key name and those fields will not have the POD tag, including in subelements that have the same field key name. Subelements will begin with "=begin $key_name" and end with "=end $key_name", and will be indented four spaces relative to their parent elements. Related stories and media will be identified by the tag specifed via the "RELATED_DOC_POD_TAG" bricolage.conf directive or default to "=related_story_uuid" and "=related_media_uuid" tags, respectively.

$container->update_from_pod($pod);
$container->update_from_pod($pod, $field_key_name);
    Updates an element and all of its subelements from POD markup such as that output by "deserialize_pod()". Any equal signs after two newlines that do not indicate a new field or element must be escaped with a slash. If $field_key_name is passed, then any blocks of text that do not have a POD tag will be assumed to be instances of that field.

    Subelements are supported using "=begin key_name" and "=end key_name" tags, although the key namee in the "=end" tag is optional. Subelements may be indented, although the root element must not be indented. Indentation of a subelement is deterimined by the amount of whitespace before the "=begin" tag. That whitespace will be trimmed from the beginning of all lines in the subelement; any extra whitespace before lines will remain intact, enabling the use of whitespace for formatting.

    The contents of $pod will be split on "/\r?\n|\r/" to be parsed on a line-by-line basis. The line endings will all be replaced with "\n" only.

    Any type of field may be specified in the POD. Dates, however, must be in ISO-8601-compliant format ("YYYY-MM-DD hh:mm:ss") to be properly parsed. Fields allowing only a limited number of values (such as pulldown or radio fields) must have content corresponding to the available values. Fields that allow multiple values (multiple select lists) are not supported.

    Related media and related stories may be identified by using one of the following tags as the first tags to appear in an element, either at the beginning of the POD or just afer a subelement's "=begin" tag:

    =related_story_uuid
    =related_media_uuid
    =related_story_uri
    =related_media_uri
    =related_story_id
    =related_media_id
    =related_story_url
    =related_media_url

    For the last two options, the domain name will be extracted from the URL in order to determine the site to search for the path section of the URL. For example, specifying

      =related_story_url http://www.example.com/foo/bar/

    will result in "update_from_pod()" searchging for the URI "/foo/bar/" associated with the site with the domain name "www.example.com".

    Throws:

    Bric::Util::Fault::Error::Invalid
        *   No context for content beginning at line [_1].

        *   No such field "[_1]" at line [_2]. Did you mean "[_3]"?

        *   No such subelement "[_1]" at line [_2]. Did you mean "[_3]"?

        *   Non-repeatable field "[_1]" appears more than once beginning at line [_2]. Please remove all but one.

        *   Unknown tag "[_1]" at line [_2].

        *   No such site "[_1]" at line [_2].

        *   No such URI "[_1]" in site "[_2]" at line [_3].

        *   No story document found for UUID "[_1]" at line [_2].

        *   No media document found for UUID "[_1]" at line [_2].

        *   No story document found for ID "[_1]" at line [_2].

        *   No media document found for ID "[_1]" at line [_2].

        *   No story document found for URI "[_1]" at line [_2].

        *   No media document found for URI "[_1]" at line [_2].

    Side Effects: Existing fields and subelements may be deleted or have their values altered. New fields and subelements may be added.

    Notes: The values provided for fields allowing only a limited number of values (such as pulldown or radio fields) are not currently enforced to be one of those values.

PRIVATE

  Private Class Methods

Bric::Biz::Element::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.

NOTES
NONE

AUTHORS
Michael Soderstrom <miraso@pacbell.net>

Refactoring and POD serialization and parsing by David Wheeler <david@kineticode.com>

SEE ALSO
perl, Bric, Bric::Biz::Asset, Bric::Biz::Asset::Business, Bric::Biz::Element