Bric::Biz::Element::CoUsernContributed Perl DBric::Biz::Element::Container(3p)



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

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-09-06 00:55:58 +0200 (Wed, 06 Sep 2006) $

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_element(\@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
               o   No context for content beginning at line [_1].

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

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

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

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

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

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

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

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

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

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

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

               o   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



perl v5.12.2                      2006-09-05 Bric::Biz::Element::Container(3p)
