Bric::Biz::Element::FiUser3Contributed Perl DocumBric::Biz::Element::Field(3p)



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

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-06-12 22:15:48 +0200 (Mon, 12 Jun 2006) $

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:

           o   Object of type $obj_class not allowed to have elements.

           o   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:

           o   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:

           o   Object must be a media or story to add elements.

           Side Effects: NONE.

           Notes: NONE.

NOTES
       NONE

AUTHORS
       Michael Soderstrom <miraso@pacbell.net>

       Refactored 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-06-12     Bric::Biz::Element::Field(3p)
