Bric::Biz::ElementTypeUser Contributed Perl DocumentBric::Biz::ElementType(3p)



NAME
       Bric::Biz::ElementType - Bricolage element types

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-03-15 00:45:41 +0100 (Wed, 15 Mar 2006) $

SYNOPSIS
         # Create new types of elements.
         $element = Bric::Biz::ElementType->new($init)
         $element = Bric::Biz::ElementType->lookup({id => $id})
         ($at_list || @ats) = Bric::Biz::ElementType->list($param)
         ($id_list || @ids) = Bric::Biz::ElementType->list_ids($param)

         # Return the ID of this object.
         $id = $element->get_id()

         # Get/set this element type's name.
         $element = $element->set_name( $name )
         $name       = $element->get_name()

         # Get/set the description for this element type
         $element  = $element->set_description($description)
         $description = $element->get_description()

         # Get/set the primary output channel ID for this element type.
         $element = $element->set_primary_oc_id($oc_id, $site_id);
         $oc_id = $element->get_primary_oc_id($site_id);

         # Attribute methods.
         $val  = $element->set_attr($name, $value);
         $val  = $element->get_attr($name);
         \%val = $element->all_attr;

         # Attribute metadata methods.
         $val = $element->set_meta($name, $meta, $value);
         $val = $element->get_meta($name, $meta);

         # Manage output channels.
         $element        = $element->add_output_channels([$output_channel])
         ($oc_list || @ocs) = $element->get_output_channels()
         $element        = $element->delete_output_channels([$output_channel])

         # Manage sites
         $element               = $element->add_sites([$site])
         ($site_list || @sites) = $element->get_sites()
         $element               = $element->remove_sites([$site])

         # Manage the parts of an element type.
         $element            = $element->add_field_types($field);
         $field_type         = $element->new_field_type($param);
         $element            = $element->copy_field_type($at, $field);
         ($part_list || @parts) = $element->get_field_types($field);
         $element            = $element->del_field_types($field);

         # Add, retrieve and delete containers from this element type.
         $element            = $element->add_containers($at || [$at]);
         (@at_list || $at_list) = $element->get_containers();
         $element            = $element->del_containers($at || [$at]);

         # Get/set the active flag.
         $element  = $element->activate()
         $element  = $element->deactivate()
         (undef || 1) = $element->is_active()

         # Save this element type.
         $element = $element->save()

DESCRIPTION
       The element type class registers new type of elements that define the
       structures of story and media documents. Element type objects are
       composed of subelement types and fields, and top-level (story and media
       type) element types are associated with sites and output channels to
       define how documents based on them will be output and in what sites
       they can be created.

INTERFACE
   Constructors
       $element = Bric::Biz::ElementType->new($init)
           Will return a new element type object with the optional initial
           state

           Supported Keys:

           name
           key_name
           description
           top_level
               Defaults to false.

           paginated
               Defaults to false.

           fixed_uri
               Defaults to false.

           related_story
               Defaults to false.

           related_media
               Defaults to false.

           media
               Defaults to false.

           biz_class_id
               Defaults to the ID for Bric::Biz::Asset::Business::Story.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $element = Bric::Biz::ElementType->lookup({id => $id})
       $element = Bric::Biz::ElementType->lookup({key_name => $key_name})
           Looks up and instantiates a new Bric::Biz::ElementType object based
           on the Bric::Biz::ElementType object ID or name passed. If $id or
           $key_name is not found in the database, "lookup()" returns "undef".

           Throws:

           o   Too many Bric::Biz::ElementType objects found.

           Side Effects: NONE

           Notes: NONE

       ($at_list || @at_list) = Bric::Biz::ElementType->list($param);
           This will return a list of objects that match the criteria defined.

           Supported Keys:

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

           name
               The name of the element type. Matched with case-insentive LIKE.
               May use "ANY" for a list of possible values.

           key_name
               The unique key name of the element type. Matched with case
               insensitive LIKE. May use "ANY" for a list of possible values.

           description
               The description of the element type. Matched with case-
               insentive LIKE. May use "ANY" for a list of possible values.

           output_channel_id
               The ID of an output channel. Returned will be all ElementType
               objects that contain this output channel. May use "ANY" for a
               list of possible values.

           field_name
           data_name
               The name of an ElementType::Parts::FieldType (field type)
               object. Returned will be all ElementType objects that reference
               this particular field type object. May use "ANY" for a list of
               possible values.

           active
               Boolean value for active or inactive element types.

           type_id
               Match elements of a particular attype. May use "ANY" for a list
               of possible values.

           site_id
               Match against the given site_id. May use "ANY" for a list of
               possible values.

           top_level
               Boolean value for top-level (story type and media type) element
               types.

           media
               Boolean value for media element types.

           paginated
               Boolean value for paginated element types.

           fixed_uri
               Boolean value for fixed URI element types.

           related_story
               Boolean value for related story element types.

           related_media
               Boolean value for related media element types.

           biz_class_id
               The ID of a Bric::Util::Class object representing a business
               class. The ID must be for a class object representing one of
               Bric::Biz::Asset::Business::Story,
               Bric::Biz::Asset::Business::Media, or one of its subclasses.
               May use "ANY" for a list of possible values.

           Throws:

           Exception::DA
       ($at_list || @ats) = Bric::Biz::ElementType->list_ids($param)
           This will return a list of objects that match the criteria defined.
           See the "list()" method for the allowed keys of the $param hash
           reference.

           Throws:

           NONE

           Side Effects:

           NONE

           Notes:

           NONE

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

   Public Class Methods
       $meths = Bric::Biz::ElementType->my_meths
       (@meths || $meths_aref) = Bric::Biz::ElementType->my_meths(TRUE)
       my (@meths || $meths_aref) = Bric::Biz::ElementType->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.

   Accessors
       id

         my $id = $element_type->get_id;

       Returns the element type object's unique database ID.

       name

         my $name = $element_type->get_name;
         $element_type = $element_type->set_name($name);

       Get and set the element type object's unique name.

       description

         my $description = $element_type->get_description;
         $element_type = $element_type->set_description($description);

       Get and set the element type object's description.

       key_name

         my $key_name = $element_type->get_key_name;
         $element_type = $element_type->set_key_name($key_name);

       Get and set the element type object's unique key name.

       top_level

         my $is_top_level = $element_type->is_top_level;
         $element_type = $element_type->set_top_level($is_top_level);

       The "top_level" attribute is a boolean that indicates whether the
       element type is a story type or a media type, and therefore a top-level
       element. In other words, elements based on it cannot be subelements of
       any other elements.

       biz_type_id

         my $biz_type_id = $element_type->get_biz_type_id;
         $element_type = $element_type->set_biz_type_id($biz_type_id);

       The "biz_type_id" attribute is contains the ID for a
       "Bric::Util::Class|Bric::Util::Class" indicating the class of object
       with whic the elements based on the type can be associated. The values
       allowed are only those for Bric::Biz::Asset::Business::Story,
       Bric::Biz::Asset::Business::Media, and the latter's subclasses.

       paginated

         my $is_paginated = $element_type->is_paginated;
         $element_type = $element_type->set_paginated($is_paginated);

       The "paginated" attribute is a boolean that indicates whether the
       elements based on the element type represent pages. Paginated elements
       generally trigger the output of multiple files, one for each paginated
       element in a document, by the burner. This attribute is ignored for top
       level elements.

       fixed_uri

         my $is_fixed_uri = $element_type->is_fixed_uri;
         $element_type = $element_type->set_fixed_uri($is_fixed_uri);

       The "fixed_uri" attribute is a boolean that indicates whether documents
       based on the element type will use the "URI Format" or "Fixed URI
       Format" of an output channel through which the document is published.
       This attribute is ignored for non-top level elements.

       related_story

         my $is_related_story = $element_type->is_related_story;
         $element_type = $element_type->set_related_story($is_related_story);

       The "related_story" attribute is a boolean that indicates whether
       elements based on the element type can have another story related to
       them.

       related_media

         my $is_related_media = $element_type->is_related_media;
         $element_type = $element_type->set_related_media($is_related_media);

       The "related_media" attribute is a boolean that indicates whether
       elements based on the element type can have another media related to
       them.

       media

         my $is_media = $element_type->is_media;
         $element_type = $element_type->set_media($is_media);

       The "media" attribute is a boolean that indicates whether elements
       based on the element type are media documents. This attribute is a
       redundant combination fo the "biz_type_id" and "top_level" attributes.

       biz_class_id

         my $biz_class_id   = $element_type->get_biz_class_id;
         my $biz_class_name = $element_type->get_biz_class;
         $element_type->set_biz_class_id($biz_class_id);

       Get and set the ID of the Bric::Util::Class object that represents the
       class for which elements of this type can be created. Must be the ID
       for either Bric::Biz::Asset::Business::Story,
       Bric::Biz::Asset::Business::Media, or one of its subclasses.
       "get_biz_class()" actually returns the package name of the business
       class represented by the "biz_class_id" attribute.

       primary_oc_id

         my $primary_oc_id = $element_type->get_primary_oc_id($site_id);
            $primary_oc_id = $element_type->get_primary_oc_id($site);

         $element_type->set_primary_oc_id($primary_oc_id, $site_id);
         $element_type->set_primary_oc_id($primary_oc_id, $site);

       Gets and sets the primary output channel within the given site for the
       element type. Either a site object or ID can be used. Only top-level
       element types have site and output channel associations.

       Throws:

       o   No site parameter passed to
           Bric::Biz::ElementType->set_primary_oc_id

       o   No output channels associated with non top-level element types.

       Side Effects: NONE.

       Notes: NONE.

       active

         my $is_active = $element_type->is_active;
         $element_type->activate;
         $element_type->deactivate;

       This boolean attribute indicates whether the element type is active.

   Instance Methods
       Output Channels

       get_output_channels
             my @ocs = $element_type->get_output_channels;
                @ocs = $element_type->get_output_channels(@oc_ids);
             my $ocs_aref = $element_type->get_output_channels;
                $ocs_aref = $element_type->get_output_channels(@oc_ids);

           Returns a list or array reference of output channels that have been
           associated with this element type. If @oc_ids is passed, then only
           the output channels with those IDs are returned, if they're
           associated with this element type.

           Throws: NONE.

           Side Effects: NONE.

           Notes: The objects returned will be
           Bric::Biz::OutputChannel::Element objects, and these objects
           contain extra information relevant to the assocation between each
           output channel and this element object.

       add_output_channel
             $element_type->add_output_channel($oc);
             $element_type->add_output_channel($oc_id);

           Adds an output channel to this element object and returns the
           resulting Bric::Biz::OutputChannel::Element object. Can pass in
           either an output channel object or an output channel ID.

           Throws: NONE.

           Side Effects: If a Bric::Biz::OutputChannel object is passed in as
           the first argument, it will be converted into a
           Bric::Biz::OutputChannel::Element object.

           Notes: NONE.

       add_output_channels
             $element_type->add_output_channels(@ocs);
             $element_type->add_output_channels(\@ocs);
             $element_type->add_output_channels(@oc_ids);
             $element_type->add_output_channels(\@oc_ids);

           This accepts a list or array reference of output channel objects or
           IDs to be associated with this element type.

           Throws: NONE.

           Side Effects: Any Bric::Biz::OutputChannel objects passed in will
           be converted into Bric::Biz::OutputChannel::Element objects.

           Notes: NONE.

       delete_output_channels
             $element_type->delete_output_channels(@output_channels);
             $element_type->delete_output_channels(\@output_channels);

           This accepts a list or array reference of output channels and
           removes their association from the object.

           Throws:

           o   Cannot delete a primary output channel.

           Side Effects: NONE.

           Notes: NONE.

       Sites

       get_sites
             my @sites = $element_type->get_sites;
                @sites = $element_type->get_sites(@site_ids);
             my $sites_aref = $element_type->get_sites;
                $sites_aref = $element_type->get_sites(@site_ids);

           Returns a list or array reference of sites that have been
           asssociated with this element type. If @site_ids is passed, then
           only the sites with those IDs are returned, if they're associated
           with this element type.

           Throws: NONE.

           Side Effects: NONE.

           Notes: The objects returned will be Bric::Biz::Site objects, and
           these objects contain extra information relevant to the assocation
           between each output channel and this element object.

       add_site
             $element_type->add_site($site);
             $element_type->add_site($site_id);

           Adds a site to this element object and returns the resulting
           Bric::Biz::Site object. Can pass in either an site object or a site
           ID.

           Throws:

           o   You can only add sites to top level objects

           o   Cannot add sites to non top-level element types.

           o   No such site.

           Side Effects: NONE.

           Notes: NONE.

       add_sites
             $element_type->add_sites(@sites);
             $element_type->add_sites(\@sites);
             $element_type->add_sites(@site_ids);
             $element_type->add_sites(\@site_ids);

           This accepts a list or array reference of site objects or IDs to be
           associated with this element type.

           Throws:

           o   You can only add sites to top level objects

           o   Couldn't find site

           Side Effects: NONE.

           Notes: NONE.

       remove_sites
             $element_type->remove_sites(@sites);
             $element_type->remove_sites(\@sites);

           Removes a list or array reference of sites from association with
           the element type.

           Throws:

           o   Cannot remove last site from an element type.

           Side Effects: Also disassociates any output channels for the site
           that are associated with this element.

           Notes: NONE.

       Field Types

       get_field_types
       get_data
             my @field_types = $element_type->get_field_types;
             my $field_type  = $element_type->get_field_types($key_name);
                @field_types = $element_type->get_data;
                $field_type  = $element_type->get_data($key_name);

           Returns a list or array reference of the field types that the
           element type contains. Pass in a key name to get back a single
           field type.

           Note: "get_data()" is the deprecated form of this method.

       add_field_types
       add_data
             $element_type->add_field_types(@field_types);
             $element_type->add_field_types(\@field_types);
             $element_type->add_data(@field_types);
             $element_type->add_data(\@field_types);

           This takes a list of field typess and associates them with the
           element type object.

           Note: "add_data()" is the deprecated form of this method.

       new_field_type
       new_data
             my $field_type = $element_type->new_field_type(\%params);
                $field_type = $element_type->new_data(\%params);

           Adds a new field type to the element type, creating a new
           Bric::Biz::ElementType::Parts::FieldType object. See
           Bric::Biz::ElementType::Parts::FieldType for a list of the
           parameters to its "new()" method for the parameters that can be
           specified in the parameters hash reference passsed to
           "new_field_type()".

           Note: "new_data()" is the deprecated form of this method.

       copy_field_type
       copy_data
             my $field_type = $element_type->copy_field_type(\%params);
                $field_type = $element_type->copy_data(\%params);

           Copies the definition for a field type from another eelement type.
           The parameters expected in the hash reference argument are:

           field_type
           field_obj
               The field type object to copy into this element type. Required
               unless "element_type" and "field_key_name" have been specified.

           element_type
           at  An existing element type object from which to extract a field
               to copy.  Required unless "field_type" has been specified.

           field_key_name
           field_name
               The key name of a field associated with the element type passed
               via the "element_type" parameter. Required unless "field_type"
               has been specified.

           Note: "copy_data()" is the deprecated form of this method.

       del_field_types
       del_data
             $element_type->del_field_types(@field_types);
             $element_type->del_field_types(\@field_types);
             $element_type->del_data(@field_types);
             $element_type->del_data(\@field_types);

           Removes the specified field types from the element type.

           Note: "del_data()" is the deprecated form of this method.

       Containers

       add_containers
             $element_type->add_containers(@element_types);
             $element_type->add_containers(\@element_types);

           Add element types to the element type as subelement types.

       get_containers
             my @element_types      = $element_type->get_containers;
             my $element_types_aref = $element_type->get_containers;
             my $element_type       = $element_type->get_containers($key_name);

           Returns all subelement element types.

       del_containers
             $element_type->del_containers(@element_types);
             $element_type->del_containers(\@element_types);

           Remove subelement element types from the element type. The
           subelement element types will not be deactivated, just
           disassociated with the parent element type.

       save

         $element_type->save;

       Saves changes to the element type, including its subelement element
       type and field type associatesions, to the database.

       Arbitrary Attribute Management

         $val = $element_type->set_attr($name => $value);
         $val = $element_type->get_attr($name);
         $val = $element_type->del_attr($name);

       Get/Set/Delete attributes on this element type.

       Arbitrary Attribute Metadata Management

         $val = $element_type->set_meta($name, $field => $value);
         $val = $element_type->get_meta($name => $field);
         $val = $element_type->get_meta($name);

       Get/Set attribute metadata on this element type. Calling the
       "get_meta()" method without $field returns all metadata names and
       values as a hash.

PRIVATE
   Private Class Methods
       _do_list
           called from list and list ids this will query the db and return
           either ids or objects

   Private Instance Methods
       These need documenting.

       _is_referenced
       $element_type->$remove
           Removes this object completely from the DB. Returns 1 if active or
           undef otherwise

       _get_attr_obj
       _get_at_type_obj
       _save_attr
       _get_element_type_grp
       _sync_parts
       $element_type->_update_element_type()
           Update values in the element_type table.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $element_type->_insert_element_type()
           Insert new values into the element_type table.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $element_type->_get_parts()
           Call the list function of Bric::Biz::ElementType::Parts::Container
           to return a list of conainer parts of this ElementType object, or
           return the existing parts if weve already loaded them.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

   Private Functions
       my $oc_coll = $get_oc_coll->($element_type)
           Returns the collection of output channels for this element type.
           The collection is a Bric::Util::Coll::OCElement object. See that
           class and its parent, Bric::Util::Coll, for interface details.

           Throws:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           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.

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

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

           Side Effects: NONE.

           Notes: NONE.

       my $site_coll = $get_site_coll->($element_type)
           Returns the collection of sites for this element type. The
           collection is a Bric::Util::Coll::Site object. See that class and
           its parent, Bric::Util::Coll, for interface details.

           Throws:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           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.

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

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

           Side Effects: NONE.

           Notes: NONE.

       my $key_name = $make_key_name->($name)
           Takes an element type name and turns it into the key name. This is
           the name that will be used in templates and in the super bulk edit
           interface.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

NOTES
       NONE.

AUTHOR
       Michael Soderstrom <miraso@pacbell.net>

       Refactored by David Wheeler <david@kineticode.com>

SEE ALSO
       Bric::Biz::Element, Bric::Util::Coll::OCElement.



perl v5.12.2                      2006-03-14        Bric::Biz::ElementType(3p)
