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



NAME
       Bric::Biz::Asset::Business::Story - The interface to the Story Object

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2007-03-27 12:46:12 +0200 (Tue, 27 Mar 2007) $

SYNOPSIS
        # creation of new objects
        $story = Bric::Biz::Asset::Business::Story->new( $init )
        $story = Bric::Biz::Asset::Business::Story->lookup( $param )
        ($stories || @stories) = Bric::Biz::Asset::Business::Story->list($param)

        # list of object ids
        ($ids || @ids) = Bric::Biz::Asset::Business::Story->list_ids($param)

        # Type of workflow.
        my $wf_type = Bric::Biz::Asset::Business::Story->workflow_type;

         # General information
        $asset       = $asset->get_id()
        $asset       = $asset->set_description($description)
        $description = $asset->get_description()

        # User information
        $usr_id      = $asset->get_user__id()
        $asset       = $asset->set_user__id($usr_id)

        # Version information
        $vers_grp_id = $asset->get_version_grp__id();
        $vers_id     = $asset->get_asset_version_id();

        # Desk information
        $desk        = $asset->get_current_desk;
        $asset       = $asset->set_current_desk($desk);

        # Workflow methods.
        $id  = $asset->get_workflow_id;
        $obj = $asset->get_workflow_object;
        $id  = $asset->set_workflow_id;

        # Access note information
        $asset         = $asset->set_note($note);
        my $note       = $asset->get_note;
        my $notes_href = $asset->get_notes()

        # Access active status
        $asset            = $asset->deactivate()
        $asset            = $asset->activate()
        ($asset || undef) = $asset->is_active()

        # Publish info
        $needs_publish = $asset->needs_publish();

        ## METHODS INHERITED FROM Bric::Biz::Asset::Business ##

        # General info
        $name = $biz->get_name()
        $biz  = $biz->set_name($name)
        $ver  = $biz->get_version()

        # Element Type information
        $elem_type   = $biz->get_element_type;
        $name        = $biz->get_element_name()
        $at_id       = $biz->get_element_type_id()
        $biz         = $biz->set_element_type_id($at_id)

        # Element methods
        $element  = $biz->get_element_type()
        @elements = $biz->get_elements()
        $biz      = $biz->add_field($field_type_obj, $data)
        $value    = $biz->get_value($name, $obj_order)
        $parts    = $biz->get_possible_field_types()

        # Container methods
        $new_container = $biz->add_container($at_contaier_obj)
        $container     = $biz->get_container($name, $obj_order)
        @containes     = $biz->get_possible_containers()

        # Access Categories
        $cat             = $biz->get_primary_category;
        $biz             = $biz->set_primary_category($cat);
        ($cats || @cats) = $biz->get_secondary_categories($sortby);
        $biz             = $biz->add_categories([$category, ...])
        ($cats || @cats) = $biz->get_categories()
        $biz             = $biz->delete_categories([$category, ...]);

        # Access keywords
        $biz               = $biz->add_keywords(\@kws)
        ($kw_list || @kws) = $biz->get_keywords()
        ($self || undef)   = $biz->has_keyword($keyword)
        $biz               = $biz->del_keywords([$kw, ...])

        # Change control
        $biz            = $biz->cancel()
        $biz            = $biz->revert($version)
        (undef || $biz) = $biz->checkin()
        $biz            = $biz->checkout($param)


        ## INSTANCE METHODS FOR Bric::Biz::Asset::Business::Story

        # Manipulation of slug field
        $slug  = $story->get_slug()
        $story = $story->set_slug($slug)

        # Access the source ID
        $src_id = $story->get_source__id()

        # Change control
        ($story || undef) = $story->is_current()

        # Ad string management
        $story         = $story->delete_ad_param($key)
        $ad_param_hash = $story->get_ad_param()
        $story         = $story->set_ad_param($key ,$val);

        # Publish data
        $date  = $story->get_expire_date()
        $story = $story->set_expire_date()

        $date  = $story->get_publish_date()
        $story = $story->set_publish_date()

        # Save to the database
        $story = $story->save()

DESCRIPTION
       Story contains all of the data that will result in published page(s) It
       contains the metadata and associations with story documents. It
       inherits from Bric::Biz::Asset::Business

INTERFACE
   Constructors
       $story = Bric::Biz::Asset::Business::Story->new( $initial_state )
           This will create a new story 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   slug

           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

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $story = Bric::Biz::Asset::Business::Story->lookup( { id => $id })
           This will return a story asset that matches the id provided

           Throws:

           "Missing required parameter 'id'"

           Side Effects:

           NONE

           Notes:

           Inherited from Asset

       (@stories||$stories) = Bric::Biz::Asset::Business::Story->list($params)
           Returns a list or anonymous array of
           Bric::Biz::Asset::Business::Story objects based on the search
           parameters passed via an anonymous hash. The supported lookup keys
           are:

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

           name
               Same as "title".

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

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

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

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

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

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

           slug
               The story slug. 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 stories.

           checked_in
               If passed a true value, this parameter causes the checked in
               version of the most current version of the story to be
               returned. When a story 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 story checked out and
               wish to see the story as of the last check in, rather than as
               currently being worked on in the current checkout. If a story
               is not currently checked out, this parameter has no effect.

           published_version
               Returns the versions of the stories 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 story listed.

           active
               Boolean indicating whether to return active or inactive
               stories.

           inactive
               Returns only inactive stories.

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

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

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

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

           note
               Returns stories 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 stories in the workflow represented by the
               workflow ID. May use "ANY" for a list of possible values.

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

           primary_uri
               Returns a list of stories with a given primary URI. May use
               "ANY" for a list of possible values.

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

           story.category
               Pass in a story ID, and a list of stories in the same
               categories as the story with that ID will be returned, minus
               the story with that ID. This parameter triggers a complex join,
               which can slow the query time significantly on underpowered
               servers or systems with a large number of stories. Still, it
               can be very useful in templates that want to create a list of
               stories in all of the categories the current story is in. But
               be sure to use the <Limit> parameter!

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

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

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

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

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

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

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

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

           grp_id
               Returns a list of stories 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 stories.

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

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

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

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

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

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

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

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

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

           element_key_name
               The key name for the story 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
               story. May use "ANY" for a list of possible values.

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

           related_story_id
               Returns a list of stories 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 stories 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 story 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.

           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".

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

           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
           This is a dummy method to save autoload the time to find it

   Public Class Methods
       ($ids || @ids) = Bric::Biz::Asset::Business::Story->list_ids( $criteria
       )
           Returns an unordered list or array reference of story object IDs
           that match the criteria defined. The criteria are the same as those
           for the "list()" method except for "Order" and "OrderDirection",
           which "list_ids()" ignore.

           See the "list()" method for the list of supported Keys.

           Throws: NONE.

           Side Effects: NONE.

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

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

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $meths = Bric::Biz::Asset::Business::Story->my_meths
       (@meths || $meths_aref) =
       Bric::Biz::Asset::Business::Story->my_meths(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. The format for each
           introspection item introspection is as follows:

           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 representing the values
               and display names to use in a select list.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

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

   Public Instance Methods
       $uri = $biz->get_uri(($cat_id||$cat_obj), ($oc_id||$oc_obj))
           Returns the a URL for this business asset. The  URL is determined
           by the pre- and post- directory strings of an output channel, the
           URI of the business object's asset type, and the cover date if the
           asset type is not a fixed URL.

           Throws:

           o   No category associated with story.

           o   Category not associated with story.

           o   Output channel not associated with story.

           Side Effects: NONE.

           Notes: NONE.

       $story = $story->set_slug($slug);
           Sets the slug for this story

           Throws:

           Slug Must conform to URL character rules.

           Side Effects:

           NONE

           Notes:

           NONE

       $slug = $story->get_slug()
           returns the slug that has been set upon this story

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       ($categories || @categories) = $ba->get_categories()
           This will return a list of categories that have been associated
           with the business asset.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $cat = $story->get_primary_category()
           Returns the category object that has been defined as primary

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $story = $story->set_primary_category($cat_id || $cat)
           Defines a category as being the the primary one for this story. If
           a category is already marked as being primary, this will
           disassociate it.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       (@cats || $cats) = $story->get_secondary_categories( $sortby )
           Returns the non-primary categories that are associated with this
           story. Takes an optional sort by field.

           Supported Keys:

           o   uri - Sort in alphabetically ascending uri order.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $ba = $ba->add_categories(@categories)
           This will take a list category objects or Is and will associate
           them with the story.

           Side Effects:

           Adds the "asset_grp_ids" of the categories to grp_ids (unless they
           are already there).

       $ba = $ba->delete_categories(@categories);
           This will take a list of categories and remove them from the story.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $story = $story->checkout()
           Preforms story specific checkout stuff and then calls checkout on
           the parent class

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       my (@gids || $gids_aref) = $story->get_grp_ids
       my (@gids || $gids_aref) =
       Bric::Biz::Asset::Business::Story->get_grp_ids
           Returns a list or anonymous array of Bric::Biz::Group object ids
           representing the groups of which this
           Bric::Biz::Asset::Business::Story object is a member.

           Throws: See Bric::Util::Grp::list().

           Side Effects: NONE.

           Notes: This list includes the Group IDs of the Desk, Workflow, and
           categories in which the story is a member. [Actually, this method
           is currently disabled, since categories don't actually add assets
           to an underlying group. If we later find that customers need to
           control access to assets based on category, we'll figure out a way
           to rectify this.]

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

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $story = $story->clone()
           Creates an identical copy of this asset with a different id

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $story = $story->save()
           Updates the story object in the database

           Throws: NONE

           Side Effects: NONE

           Notes: NONE

PRIVATE
   Private Class Methods
   Private Instance Methods
       $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_contributor($id)
           Deletes the rows from these mapping tables

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $category_data = $self->_get_categories()
           Returns the category data structure for this story

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $ba = $ba->_sync_categories
           Called by save this will make sure that all the changes in category
           mappings are reflected in the database

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $ba = $ba->_insert_category($cat_id, $primary)
           Adds a record that associates this ba with the category

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $ba = $ba->_delete_category( $cat_id)
           Removes this record for the database

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $ba = $ba->_update_category($cat_id, $primary);
           Preforms an update on the row in the data base

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_insert_story()
           Inserts a story record into the database

           Throws:

           NONE

           side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_insert_instance()
           Inserts an instance record into the database

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_update_story()
           Updates the story record in the database

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_update_instance()
           Updates the record for the story instance

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_delete_instance();
           Deletes the version record from a cancled checkout

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

       $self = $self->_delete_story();
           Deletes from the story table for a story that has never been
           checked in

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

NOTES
       NONE

AUTHOR
       Michael Soderstrom <miraso@pacbell.net>

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



perl v5.12.2                      2007-03Bric::Biz::Asset::Business::Story(3p)
