Name

Bric::Biz::Element::Field - Data (Field) Element

Synopsis

# Creation of New Objects
$data = Bric::Biz::Element::Field->new($params);
$data = Bric::Biz::Element::Field->lookup({ id => $id });
@data = Bric::Biz::Element::Field->list($params);

# Retrieval of Object IDs
@ids = = Bric::Biz::Element::Field->list_ids($params);

# Manipulation of Data Field
$data = $data->set_value( $data_value );
$data_value = $data->get_value;

Description

This class contains the contents of field elements, also known as data elements. These are the objects that hold the values of story element fields. This class inherits from Bric::Biz::Element.

Interface

Constructors

my $data = Bric::Biz::Element::Field->new($init)
Construct a new data element object. The supported initial attributes are:
- object_type
  A string identifying the type of document the new data 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 data element is associated with.
- place
  The order of this element relative to the other subelements of the parent element.
- field_type
- element_data
  The Bric::Biz::ElementType::Parts::FieldType object that defines the structure of the new data element.
- field_type_id
- element_data_id
  The ID of the Bric::Biz::ElementType::Parts::FieldType object that defines the structure of the new data element.
- parent_id
  The ID of the container element that is the parent of the new data element.
- active
  A boolean value indicating whether the container element is active or inactive.
Throws: NONE.

Side Effects: NONE.

Notes: NONE.
my $data = Bric::Biz::Element::Field->lookup($params)
Looks up a data element in the database by its ID and returns it. The lookup parameters are:
- id
  The ID of the data element to lookup. Required.
- object
  A story or media document object with which the data element is associated. Required unless object_type is specified.
- object_type
  The type of document object with which the data 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 @data = Bric::Biz::Element::Field->list($params)
Searches for and returns a list or anonymous array of data element objects. The supported parameters that can be searched are:
- object
  A story or media object with which the data elements are associated. Required unless object_type is specified.
- object_type
  The type of document with which the data elements are associated. Required unless object is specified.
- object_instance_id
  The ID of a story or data object with wich the data 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 data 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 data 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 data elements. May use ANY for a list of possible values.
- field_type_id
- element_data_id
  The ID of the Bric::Biz::ElementType::Parts::FieldType object that specifies the structure of the data 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

$data->DESTROY
Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Public Class Methods

my @ids = Bric::Biz::Element::Field->list_ids($params)
Returns a list or anonymous array of data 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::Field inherits.

my $field_type_id = $data->get_field_type_id
my $field_type_id = $data->get_element_data_id
Returns the ID of the Bric::Biz::ElementType::Parts::FieldType object that describes this element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$data->set_field_type_id($field_type_id)
$data->set_element_data_id($field_type_id)
Sets the ID of the Bric::Biz::ElementType::Parts::FieldType object that describes this element.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$field_type = $data->get_field_type
$field_type = $data->get_field_type
Returns the Bric::Biz::ElementType::Parts::FieldType object that defines the structure of this field.

Throws: NONE.

Side Effects: NONE.

Notes: get_element_data_obj is the deprecated form.
$name = $data->get_element_name
An alias for $data->get_name.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$key_name = $data->get_element_key_name
An alias for $data->get_key_name.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$data->set_value($value)
$data->set_data($value)
Sets the value of the field. Use set_values() if multiple values are allowed on the field (because the field type's multiple attribute is true).

Throws: NONE.

Side Effects: NONE.

Notes: set_data() is the deprecated form of this method.
$data->set_values(@values)
Sets multiple values for the field. Useful for setting the values for "multiple" fields such as multiple select lists.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
my $value = $value->get_value
my $value = $value->get_value($format)
my $value = $data->get_data
my $value = $data->get_data($format)
Returns the value of this data element. If the SQL type of the data object is "date", then $format, if it is passed, will be used to format the date. Otherwise, the format set in the preferences will be used.

Throws: NONE.

Side Effects: NONE.

Notes:

set_data() is the deprecated form of this method. For fields that can contain multiple values, call get_values(), instead.
$field->get_values()
```
my @values      = $field->get_values;
   @values      = $field->get_values($format);
my $fields_aref = $field->get_values;
   $fields_aref = $field->get_values($format);
```
Returns a list or array reference of all of the values associated with a field. This method should be called in preference to get_value() for fields that can contain multiple values (i.e., is_multiple() returns a true value.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
my $is_autopopulated = $data->is_autopopulated
Returns true if the field's value is autopopulate, and false if it is not.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
my $is_multiple = $data->is_multiple
Returns true if the field is allowed to have multiple values and false if it is not.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
my $get_max_length = $data->get_max_length
Returns the maximum allowed length of the field's value.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
my $sql_type = $data->get_sql_type
Returns the SQL type of the field. This value corresponds to the sql_type attribute of the Bric::Biz::ElementType::Parts::FieldType object on which the field is based.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
my $widget_type = $data->get_widget_type
Returns the string indicating the widget to use to display the field. This value corresponds to the widget_type attribute of the Bric::Biz::ElementType::Parts::FieldType object on which the field is based.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$data->prepare_clone
Prepares the data 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.
my $is_container = $data->is_container
Returns false, since data elements are not container elements.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$data->lock_val
For autopopulated data elements, this method prevents the value from being autopopulated.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$data = $data->unlock_val
Allows auotpopulated data elements to be autopopulated.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
my $is_locked = $data->is_locked
Returns true if the element has been locked.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.
$data = $data->save
Saves the changes to the data element to the database.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Private

Private Class Methods

Bric::Biz::Element::Field->_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:
- Object of type $obj_class not allowed to have elements.
- Improper args for list.
Side Effects: NONE.

Notes: NONE.

Private Instance Methods

$data->_do_insert()
Called by save(), this method inserts the data element into the database.

Throws:
- Object must be a media or story to add elements.
Side Effects: NONE.

Notes: NONE.
$data->_do_update
Called by save(), this method updates the data element into the database.

Throws:
- Object must be a media or story to add elements.
Side Effects: NONE.

Notes: NONE.

Notes

NONE

Authors

Michael Soderstrom

Refactored by David Wheeler