Bric::Biz::Element::Container

Name

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

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::AssetType object that are subelements of the parent element.
- displayed
  Boolean indicating whether or not the container element's display is toggled open in the document profile. Ignored for top-level container elements.
- 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.
- related_story_id
  The ID of a Bric::Biz::Asset::Business::Story object that may be related to 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.
- related_media_id
  The ID of a Bric::Biz::Asset::Business::Media object that may be related to 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.
- displayed
  A boolean value indicating whether the returned data elements should have their display toggled open in the document profile.
- 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 $displayed = $container->get_displayed
Returns boolean value indicating whether or not the container element's display should be toggled open in the document profile.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$container->set_displayed($displayed)
Sets the boolean value indicating whether or not the container element's display should be toggled open in the document profile.

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->get_elem_occurrence($subelement->get_key_name)
Returns the number of subelements currently in this container which match the name passed in.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$container->get_field_occurrence($field_type->get_key_name)
Returns the number of fields currently in this container which match the field name passed in.

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_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 a set number of times, and have already been added that many times. This is the max_occurrence of that FieldType.

Throws: NONE.

Side Effects: NONE.

Notes: get_possible_data() is the deprecated form of this method.
my @elementtypes = $container->get_possible_containers
Returns a list or anonymous array of the Bric::Biz::ElementType 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, with the exception that it will only return those containers that don't already have the max allowed according to the max_occurrence.

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. This returns the field that was created/added.

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. The newly added container element will be returned.

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 elements 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

Refactoring and POD serialization and parsing by David Wheeler