NAME

Myco::Base::Entity::Meta::Attribute -

VERSION

Release

0.01

Repository

$Revision$ $Date$

SYNOPSIS

 # Note this class is normally used only via
 #   Myco::Base::Entity::Meta

 ## Within an entity class definition - add attribute to class
 #   ::Attribute's constructor should only be used via
 #     ::Meta's add_attribute() as shown:

 my $md = Myco::Base::Entity::Meta( name => __PACKAGE__ );
 $md->add_attribute(
    name => 'doneness',
    type => 'int',
    readonly => 0,                     # default is read/write
    access_list => { rw => ['admin'],
                     ro => [qw(average_joes junior_admins)] },
    tangram_options => { required => 1},
    synopsis => "How you'd like your meat cooked",
    syntax_msg => "correct format, please!",
    values => [qw(0 1 2 3 4 5)],
    value_labels => {0 => 'rare',
                     1 => 'medium-rare',
                     2 => 'medium',
                     3 => 'medium-well',
                     4 => 'well',
                     5 => 'charred'},
    ui => { widget => [ 'popup_menu' ],
            label  => 'Cook until...',
          },
  );

 ## Typical post-setup usage
 #   ...given a Myco::Base::Entity::Meta enabled entity object $obj

 my $metadata = $obj->introspect;
 # Get reference to array of ::Meta::Attribute objects for $obj's class
 my $attributes = $metadata->get_attributes;
 # Look up attribute's type
 my $type = $attributes->{doneness}->get_type;
 # Use of stored accessor coderef - set doneness = 3
 $attributes->{doneness}->setval($obj, 3);

DESCRIPTION

container for meta data describing an attribute of a Myco Entity class

COMMON ENTITY INTERFACE

Constructor, accessors, and other methods -- as inherited from Myco::Base::Entity

ATTRIBUTES

Attributes may be initially set during object construction (with new()) but otherwise are accessed solely through accessor methods. Typical usage:

  • Set attribute value

     $obj->set_attributeName($value);

    Check functions (see Class::Tangram) perform data validation. If there is any concern that the set method might be called with invalid data then the call should be wrapped in an eval block to catch exceptions that would result.

  • Get attribute value

     $value = $obj->get_attributeName;

A listing of available attributes follows:

access_list

 type: hash ref

Hash containing either or both of these keys: rw, ro (for read-write, read-only, respectively). Each key corresponds to a anonymous array of names of user roles authorized for the given type of access.

getter

 type: code ref

Reference to getter method of entity attribute.

name

 type: string   required: not empty

Name of entity attribute.

readonly

 type: int (boolean)

If set to true calls to entity attribute setter will result in throwing of exception type Myco::Exception::MNI.

setter

 type: code ref

Reference to setter method of entity attribute.

synopsis

 type: string

Short (a few words) description of entity attribute.

tangram_options

 type: hash ref

Hash of Class::Tangram entity attribute options.

template

 type: int (boolean)

If set to true entity attribute is marked as a "template", meaning the following:

  • the entity class does not have use of this entity attribute (although its metadata definition is available)

  • a sub-class of this entity class will have this entity attribute added to its schema; it is added directly to the sub-class, not inherited.

type

 type: string

Data type of entity attribute; must be a valid Class::Tangram data type. [required: not undef]

### TODO: Add coverage of types here.... including Myco custom types.

type_options

 type: hash ref

Additional detail regarding the entity attribute data type. Valid option(s):

  • string_length: int

    Maximum character length of string type entity attributes. During schema generation this results in the automatic addition of

      sql => 'VARCHAR(#)'

    to the 'tangram_options' parameter, unless that parameter already has the 'sql' option set. Also, if this entity attribute employs a textfield or password_field as a user interface (either specified via the 'ui' metadata attribute or as the default [for scalars]) then the closure generated will include -maxlength => # in the CGI.pm method parameter list (see below: attribute 'ui').

syntax_msg

 type: string

Short (under one line) description of valid entity attribute value syntax.

values

 type: array ref

Array of all valid values for this entity attribute. Use only when appropriate. By default, setting this metadata parameter results in a "popup_menu" being used as the user interface widget type, with values displayed in the order given.

  • Special Array Values

    The special string values below may be included as members of the array to customize this entity attribute's user interface behavior. These values do NOT get stored in the entity object attribute.

    • __select__

      Including in the array the string "__select__" will make "<Select>" appear as a popup menu choice.

    • __other__

      If the array contains the string "__other__" then during widget generation the popup menu will include the choice "<Other>", and a text box will appear below labeled "Other:" that allows entry of an alternate value which will be used as the input value for this entity attribute if '<Other>' is selected.

    • __blank__

      If the array contains the string "__blank__" then the popup menu will contain a blank selection at the given position.

value_labels

 type: hash ref

Hash mapping entity attribute values (which should be the same as those specified with the "values" parameter) to a user visible label; for use when generating value selection user interface widget for this entity attribute.

ui

 type: hash ref

 {
  label  => 'Sprocket',
  widget => ['popup_menu', -rows => 2, -columns => 2],
  # etc.
 }

A data structure containing instructions for generating a user interface element for this entity attribute. This data structure used in the creation of a Myco::Base::Entity::Meta::Attribute::UI object which becomes part of the attribute metadata. Run-time access to this metadata should only occur via accessor methods.

The following hash keys (corresponding to ::Meta::Attribute::UI object attributes) are allowed:

  • closure

     type: code ref

    A reference to an anonymous subroutine capable of generating a user interface element for this entity object attribute. The subroutine is a closure and can be thought of as the compiled representation of all other user interface related metadata (values, value_labels, ui->widget, ui->label) for this entity attribute.

    See documentation of method create_closure() from class Myco::Base::Entity::Meta::Attribute::UI.

    This attribute is set automatically by a call to set_widget().

    label

     type: string

    Label text to appear in user iterface on or near this entity attribute's inteface widget.

    options

     type: hash ref
    
     { hidden => 1 }

    Options that affect the user interface behavior of this entity attribute. Available options:

    • hidden

       type: boolean

      If set to true indicates that a widget for this attribute should not by default be visable. However, when generating an HTML-based form for the pupose of creating/updating entity objects that contain this attribute, the attribute should be included as a hidden form field.

    • value_default

       type: string

      If the attribute metadata contains the values parameter then during widget generation the value supplied with this option is selected by default.

    • value_select

       type: boolean

      This option is automatically set to true if the attribute metadata contains the values parameter and the list of values includes the string '__select__'.

    suffix

     type: string

    Additional HTML that will be appended to the generated widget HTML.

    widget

     type: array ref
    
     ['popup_menu', -rows => 2, -columns => 2]

    The first array element is the name of the CGI.pm form element method to be used to generate the widget. Named parameters for this CGI.pm method may optionally follow. Named parameters -name, -values, and -value_labels should _not_ be specified here (these will automatically be set as appropriate, from, for example, other metadata attributes).

    Setting this attribute will trigger the automatic setting of the 'closure' attribute.

    • Default UI Widget

      If this piece of metadata is not supplied in class definition then during metadata initialization for this entity asttribute, an appropriate user interface widget may be automatically chosen, depending on the type of the entity attribute (as indicated in the 'type' metadata attribute). The default UI elements (CGI.pm form element method names) are listed below by major entity type categories:

      • scalars: textfield

        (string, int, real, rawdate, etc.) If, however, the 'values' metadata attribute is set then 'popup_menu' will be used instead.

      • flat_array: none

      • other: none

         (ref, (i)array, (i)set, hash, dmdatetime, perl_dump)

ADDED CLASS / INSTANCE METHODS

get_type_defaults

Returns a reference to a hash (key == attribute type) of default meta data info which is used during attribute object initialization.

getval

 # Given $attrmeta, an ::Attribute metadata object for some class,
 #   and $entity, an instance of same class
 $attrval = $attrmeta->getval($entity);

 # Complete, but unrealistic example of use
 $attrval = $entity->introspect->get_attributes->{attr1}
                                            ->getval($entity);

Get the value of an attribute of $entity, utilizing the getter code reference retrieved via get_getter.

setval

 # Given $attrmeta, an ::Attribute metadata object for some class,
 #   and $entity, an instance of same class
 $attrval = $attrmeta->setval($entity, $value);

 # Complete, but unrealistic example of use
 $attrval = $entity->introspect->get_attributes->{attr1}
                                         ->setval($entity, $value);

Set value of an attribute of $entity, utilizing the setter code reference retrieved via get_setter.

LICENSE AND COPYRIGHT

Copyright (c) 2004 the myco project. All rights reserved. This software is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Myco::Base::Entity::Meta, Myco::Base::Entity, CGI, Myco::Base::Entity::Meta::Attribute::Test, Myco, Tangram, Class::Tangram, mkentity