Bric::Biz::Asset::BusiUser:Contributed PeBric::Biz::Asset::Business::Media(3p)



NAME
       Bric::Biz::Asset::Business::Media - The parent class of all media
       objects

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2007-07-26 13:06:48 +0200 (Thu, 26 Jul 2007) $

SYNOPSIS
         use Bric::Biz::Asset::Business::Media;

DESCRIPTION
       Media contains all of the data that will result in published media
       files. It contains the metadata and associations with media documents.
       It inherits from Bric::Biz::Asset::Business

INTERFACE
   Constructors
       $media = Bric::Biz::Asset::Business::Media->new( $initial_state )
           This will create a new media object with an optionally defined
           initial state

           Supported Keys:

           o   user__id - Required.

           o   active

           o   priority

           o   title - same as name

           o   name - Will be overridden by title

           o   description

           o   workflow_id

           o   element_type_id - Required unless asset type object passed

           o   element_type - the object required unless id is passed

           o   site_id - required

           o   source__id - required

           o   cover_date - will set expire date in conjunction with the
               source

           o   media_type_id

           o   category__id

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $media = Bric::Biz::Asset::Business::Media->lookup( { id => $id })
           This will return a media asset that matches the criteria defined

           Throws: NONE.

           Side Effects: NONE.

           Notes: Inherited from Bric::Biz::Asset.

       (@media || $media) =  Bric::Biz::Asset::Business::Media->list($param);
           returns a list or list ref of media objects that match the criteria
           defined

           Supported Keys:

           title
               The title of the media document. May use "ANY" for a list of
               possible values.

           name
               Same as "title".

           description
               Media Document description. May use "ANY" for a list of
               possible values.

           id  The media document ID. May use "ANY" for a list of possible
               values.

           uuid
               The media document UUID. May use "ANY" for a list of possible
               values.

           exclude_id
               A media document ID to exclude from the list. May use "ANY" for
               a list of possible values.

           version
               The media document version number. May use "ANY" for a list of
               possible values.

           version_id
               The ID of a version of a media document. May use "ANY" for a
               list of possible values.

           file_name
               The media document file name. May use "ANY" for a list of
               possible values.

           user_id
               Returns the versions that are checked out by the user,
               otherwise returns the most recent version. May use "ANY" for a
               list of possible values.

           checked_out
               A boolean value indicating whether to return only checked out
               or not checked out media.

           checked_in
               If passed a true value, this parameter causes the checked in
               version of the most current version of the media document to be
               returned. When a media document is checked out, there are two
               instances of the current version: the one checked in last, and
               the one currently being edited. When the "checked_in" parameter
               is a true value, then the instance last checked in is returned,
               rather than the instance currently checked out. This is useful
               for users who do not currently have a media document checked
               out and wish to see the media document as of the last check in,
               rather than as currently being worked on in the current
               checkout. If a media document is not currently checked out,
               this parameter has no effect.

           published_version
               Returns the versions of the media documents as they were last
               published. The "checked_out" parameter will be ignored if this
               parameter is passed a true value.

           return_versions
               Boolean indicating whether to return pass version objects for
               each media document listed.

           active
               Boolean indicating whether to return active or inactive media.

           inactive
               Returns only inactive media.

           alias_id
               Returns a list of media aliased to the media ID passed as its
               value. May use "ANY" for a list of possible values.

           category_id
               Returns a list of media in the category represented by a
               category ID. May use "ANY" for a list of possible values.

           category_uri
               Returns a list of media with a given category URI. May use
               "ANY" for a list of possible values.

           keyword
               Returns media associated with a given keyword string (not
               object). May use "ANY" for a list of possible values.

           note
               Returns media with a note matching the value associated with
               any of their versions. May use "ANY" for a list of possible
               values.

           workflow_id
               Return a list of media in the workflow represented by the
               workflow ID. May use "ANY" for a list of possible values.

           desk_id
               Returns a list of media on a desk with the given ID. May use
               "ANY" for a list of possible values.

           uri Returns a list of media with a given URI. May use "ANY" for a
               list of possible values.

           site_id
               Returns a list of media associated with a given site ID. May
               use "ANY" for a list of possible values.

           site
               Returns a list of media associated with a given site name. May
               use "ANY" for a list of possible values.

           element_type_id
               Returns a list of media associated with a given element type
               ID. May use "ANY" for a list of possible values.

           source_id
               Returns a list of media associated with a given source ID. May
               use "ANY" for a list of possible values.

           output_channel_id
               Returns a list of media associated with a given output channel
               ID. May use "ANY" for a list of possible values.

           primary_oc_id
               Returns a list of media associated with a given primary output
               channel ID. May use "ANY" for a list of possible values.

           priority
               Returns a list of media associated with a given priority value.
               May use "ANY" for a list of possible values.

           contrib_id
               Returns a list of media associated with a given contributor ID.
               May use "ANY" for a list of possible values.

           grp_id
               Returns a list of media that are members of the group with the
               specified group ID. May use "ANY" for a list of possible
               values.

           publish_status
               Boolean value indicating whether to return published or
               unpublished media.

           first_publish_date_start
               Returns a list of media first published on or after a given
               date/time.

           first_publish_date_end
               Returns a list of media first published on or before a given
               date/time.

           publish_date_start
               Returns a list of media last published on or after a given
               date/time.

           publish_date_end
               Returns a list of media last published on or before a given
               date/time.

           cover_date_start
               Returns a list of media with a cover date on or after a given
               date/time.

           cover_date_end
               Returns a list of media with a cover date on or before a given
               date/time.

           expire_date_start
               Returns a list of media with a expire date on or after a given
               date/time.

           expire_date_end
               Returns a list of media with a expire date on or before a given
               date/time.

           unexpired
               A boolean parameter. Returns a list of media without an expire
               date, or with an expire date set in the future.

           element_key_name
               The key name for the media type element. May use "ANY" for a
               list of possible values.

           subelement_key_name
               The key name for a container element that's a subelement of a
               media document. May use "ANY" for a list of possible values.

           subelement_id
               The ID for a container element that's a subelement of a media
               document. May use "ANY" for a list of possible values.

           related_story_id
               Returns a list of media that have this story ID as a related
               story. May use "ANY" for a list of possible values.

           related_media_id
               Returns a list of media that have this media ID as a related
               media document.  May use "ANY" for a list of possible values.

           data_text
               Text stored in the fields of the media element or any of its
               subelements. Only fields that use the "short" storage type will
               be searched. May use "ANY" for a list of possible values.

           simple
               Triggers a single OR search that hits title, description, uri
               and keywords.

           Order
               A property name or array reference of property names to order
               by.

           OrderDirection
               The direction in which to order the records, either "ASC" for
               ascending (the default) or "DESC" for descending. This value is
               applied to the property specified by the "Order" parameter, and
               may also be an array reference. If no value is supplied for any
               "Order" property name, it will default to ascending.

           Limit
               A maximum number of objects to return. If not specified, all
               objects that match the query will be returned.

           Offset
               The number of objects to skip before listing the remaining
               objcts or the number of objects specified by "Limit".

           Throws:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

           Side Effects:

           NONE

           Notes: Inherited from Bric::Biz::Asset.

   Destructors
       $self->DESTROY
           dummy method to not waste the time of AUTOLOAD

   Public Class Methods
       (@ids||$id_list) = Bric::Biz::Asset::Business::Media->list_ids(
       $criteria );
           Returns a list or list ref of media object IDs that match the
           criteria defined.  The criteria are the same as those for the
           list() method.

           Throws: NONE.

           Side Effects: NONE.

           Notes: Inherited from Bric::Biz::Asset.

       ($fields || @fields) =
       Bric::Biz::Asset::Business::Media::autopopulated_fields()
           Returns a list of the names of fields that are registered in the
           database as being autopopulatable for a given sub class

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       my $key_name = Bric::Biz::Asset::Business::Media->key_name()
           Returns the key name of this class.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       my $hashref = Bric::Biz::Asset::Business::Media->thumbnail_uri()
           This method returns a local URI pointing to an icon representing
           the media type of the media document. If no file has been uploaded
           to the media document, "thumbnail_uri()" will return "undef".

           This method is only enabled if the "USE_THUMBNAILS" bricolage.conf
           directive is enabled. It may be overridden in subclasses to return
           a different URI value (See Bric::Biz::Asset::Business::Media::Image
           for an example).

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $meths = Bric::Biz::Asset::Business::Media->my_meths
       (@meths || $meths_aref) =
       Bric::Biz::Asset::Business::Media->my_meths(TRUE)
       my (@meths || $meths_aref) =
       Bric::Biz:::Asset::Business::Media->my_meths(0, TRUE)
           Returns an anonymous hash of introspection data for this object. If
           called with a true argument, it will return an ordered list or
           anonymous array of introspection data. If a second true argument is
           passed instead of a first, then a list or anonymous array of
           introspection data will be returned for properties that uniquely
           identify an object (excluding "id", which is assumed).

           Each hash key is the name of a property or attribute of the object.
           The value for a hash key is another anonymous hash containing the
           following keys:

           name
               The name of the property or attribute. Is the same as the hash
               key when an anonymous hash is returned.

           disp
               The display name of the property or attribute.

           get_meth
               A reference to the method that will retrieve the value of the
               property or attribute.

           get_args
               An anonymous array of arguments to pass to a call to get_meth
               in order to retrieve the value of the property or attribute.

           set_meth
               A reference to the method that will set the value of the
               property or attribute.

           set_args
               An anonymous array of arguments to pass to a call to set_meth
               in order to set the value of the property or attribute.

           type
               The type of value the property or attribute contains. There are
               only three types:

               short
               date
               blob
           len If the value is a 'short' value, this hash key contains the
               length of the field.

           search
               The property is searchable via the list() and list_ids()
               methods.

           req The property or attribute is required.

           props
               An anonymous hash of properties used to display the property or
               attribute. Possible keys include:

               type
                   The display field type. Possible values are

                   text
                   textarea
                   password
                   hidden
                   radio
                   checkbox
                   select
               length
                   The Length, in letters, to display a text or password
                   field.

               maxlength
                   The maximum length of the property or value - usually
                   defined by the SQL DDL.

           rows
               The number of rows to format in a textarea field.

           cols
               The number of columns to format in a textarea field.

           vals
               An anonymous hash of key/value pairs reprsenting the values and
               display names to use in a select list.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $class_id = Bric::Biz::Asset::Business::Media->get_class_id()
           Returns the class id of the Media object or class.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       my $wf_type = Bric::Biz::Asset::Business::Media->workflow_type
           Returns the value of the Bric::Biz::Workflow "MEDIA_WORKFLOW"
           constant.

   Public Instance Methods
       $media = $media->set_category__id($id)
           Associates this media asset with the given category

           Throws: NONE.

           Side Effects: Updates the media document's URI and group
           associations.

           Notes: NONE.

       $category_id = $media->get_category__id()
           Returns the category id that has been associated with this media
           object

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $media->set_cover_date($cover_date)
           Sets the cover date and updates the URI.

           Throws:

           o   Bric::_get() - Problems retrieving fields.

           o   Unable to unpack date.

           o   Unable to format date.

           o   Incorrect number of args to Bric::_set().

           o   Bric::set() - Problems setting fields.

           Side Effects: Changes the media document's URI.

           Notes: NONE.

       $category = $media->get_category_object()
       $category = $media->get_category()
       $category = $media->get_primary_category()
           Returns the object of the category that this is a member of

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       my $uri = $media->get_uri
       my $uri = $media->get_uri($oc)
           Returns the URI for the media object. If the $oc output channel
           parameter is passed in, then the URI will be returned in the output
           channel's preferred format.

           Throws:

           o   Output channel not associated with media.

           Side Effects: NONE.

           Notes: NONE.

       $uri = $media->get_local_uri()
           Returns the uri of the media object for the Bricolage application
           server.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $uri = $media->get_path()
           Returns the path of the media object on the Bricolage file system.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $mt_obj = $media->get_media_type()
           Returns the media type object associated with this object.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $media = $media->upload_file($file_handle, $file_name)
       $media = $media->upload_file($file_handle, $file_name, $media_type)
       $media = $media->upload_file($file_handle, $file_name, $media_type,
       $size)
           Reads a file from the passed $file_handle and stores it in the
           media object under $file_name. If $media_type is passed, it will be
           used to set the media type of the file. Otherwise, "upload_file()"
           will use Bric::Util::MediaType to determine the media type. If
           $size is passed, its value will be used for the size of the file;
           otherwise, "upload_file()" will figure out the file size itself.

           Throws: NONE.

           Side Effects: Closes the $file_handle after reading. Updates the
           media document's URI.

           Notes: NONE.

       $file_name = $media->get_file_name()
           Returns the name of the file for this given media object.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $file_handle = $media->get_file()
           Returns the file handle for this given media object

           Throws:

           o   Error getting File.

           Side Effects: NONE.

           Notes: NONE.

       $location = $media->get_location()
           The will return the location of the file on the file system,
           relative to MEDIA_FILE_ROOT.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $size = $media->get_size()
           This is the size of the media file in bytes

           Throws:

           o   Unable to retrieve category__id of this media.

           Side Effects: NONE.

           Notes: NONE.

       $media = $media->revert();
           Reverts the current version to a prior version

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $media = $media->clone()
           Clones the media object

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->save()
           Saves the object to the database doing either an insert or an
           update

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $contribs = $self->_get_contributors()
           Returns the contributors from a cache or looks em up

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_insert_contributor( $id, $role)
           Inserts a row into the mapping table for contributors.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_update_contributor($id, $role)
           Updates the contributor mapping table

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_delete_contributors($id)
           Deletes the rows from these mapping tables

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       ($fields) = $self->_get_auto_fields($biz_pkg)
           returns a hash ref of the fields that are to be autopopulated from
           this type of media object.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_insert_media()
           Inserts a media record into the database

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_update_media()
           Preforms the SQL that updates the media table

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_insert_instance()
           Preforms the sql that inserts a record into the media instance
           table

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_update_instance()
           Preforms the sql that updates the media_instance table

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_delete_media()
           Removes the media row from the database

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_delete_instance()
           Removes the instance row from the database

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_delete_file()
           Deletes the version directory for the current version if it exists.

           Throws: NONE.

           Side Effects: If the "AUTO_PREVIEW_MEDIA" bricolage.conf directive
           is enabled, the previous version of the media document will be
           looked up and its media file previewed, so as to replace the
           deleted media preview.

           Notes: NONE.

       $self = $self->_select_media($where, @bind);
           Populates the object from a database row

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_do_update()
           Updates the row in the data base

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $self = $self->_preview()
           Previews the media document.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

NOTES
       Some additional fields may be needed here such as a field for what kind
       of object this represents etc.

AUTHOR
       "Michael Soderstrom" <miraso@pacbell.net>

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



perl v5.12.2                      2007-07Bric::Biz::Asset::Business::Media(3p)
