NAME

Myco::Base::Entity::Meta

meta data container for Myco entity classes

VERSION

Release

0.01

Repository

$Revision$ $Date$

SYNOPSIS

 #### Entity class definition

 package Foo;
 use base qw(Myco::Base::Entity);

 # Constructor
 my $metadata = Myco::Base::Entity::Meta->new
  ( name => __PACKAGE__,
    access_list => {
                    rw => ['admin'],
                    ro => [qw(junior_admin plebian)]
                   },
    ui => {
           list => {
                    layout => [qw(__UI_IDENT__ attr2 attr3)]
                   },
           view => {
                    layout => [qw(attr2 attr3 attr1)]
                   }
          }
  );

 # Added attribute metadata
 $metadata->add_attribute(name => 'attr1', type => 'string');
 $metadata->add_attribute(name => 'attr2', type => 'string');

 ...  # declare more attributes, methods, etc.

 # Set access control list
 $metadata->set_access_list({rw => ['admin'],
                             ro => [qw(junior_admin plebian)]
                            });

 # Fill in $schema with all added attributes and discover other
 # metadata.  Should be placed at end of class file
 $metadata->activate_class;
 1;


 #### Entity class use

 use Foo;
 $instance = Foo->new();

 #  "introspect()" method is added to entity class
 #  automatically during the call to activate_class()

 # Access class metadata
 $metadata = Foo->introspect;
 $metadata = $instance->introspect;

 # Generate a text identifier for this object, suitable for use
 #   in UI list of like objects, etc.
 $id_string = $instance->introspect('__UI_IDENT__');

DESCRIPTION

...::Meta, as a companion to Myco::Base::Entity (and more intimately Class::Tangram) allows a class to maintain and provide access to metadata about itself. This metadata includes details regarding: attributes, methods, persistence, and user interface defaults. Metadata elements, when possible, will carry documentation pulled from respective sections of the class's POD documentation [future] (this functionality will work only when POD is formatted as shown in Myco::templates::entity.)

When used as intended, ...::Meta takes care of much of the process of entity class declaration. Object schema is declared via one or more calls of $metadata->add_attribute(), with which a rich set of metadata about a given attribute may be specified. Placed at the end of the class file is the call $metadata->activate_class, which triggers the discovery of additional class details and the generation of a Class::Tangram-style $schema data structure (along with a call to Class::Tangram::import_schema()).

Upgrading existing classes

For exisiting classes with Class::Tangram-style $schema data structures much of the functionality provide by ...::Meta may be added with just these modifications:

1. Add, after the use base ...; statement:

 my $metadata = Myco::Base::Entity::Meta->new(name => __PACKAGE__);

2. Remove this existing statement:

 Myco::Base::Entity::import_schema(__PACKAGE__);

3. Add, at end of class file:

 $metadata->activate_class;

When activate_class() is called the existing $schema will be parsed to generate as much related metadata as possible.

As is desirable, then, the schema declaration may be updated, one attribute at a time, such that attributes are declared via $metadata->add_attribute() calls, thereby allowing a more complete set of metadata to be specified.

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:

[Note the behavior described below by which some attributes provide access to sections of a class's POD documentation has not yet been implemented]

name

 type: string [required]

The name of the class described by this metadata object.

abstract

 type: string

The ABSTRACT section of the class's POD documentation.

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 an anonymous array of names user roles authorized for the given type of access.

attributes

 type: hash ref [read-only]

A hash containing metadata describing the class's object attributes. The hash maps attribute names to respective Myco::Base::Entity::Meta::Attribute objects. New entries to this hash should be added using only the add_attribute() method (described below). There is no reason why set_attributes should ever be called.

queries

 type: hash ref [read-only]

A hash containing metadata describing object attributes for any queries defined for this object. The hash is keyed my name. New entries to this hash should be added using only the add_query() method (described below). There is no reason why set_queries should ever be called.

code

 type: hash ref [read-only]

Metadata-related code references generated during the call to activate_class(). Keys that may be present (shown with example of typical usage):

• displayname

   print $metadata->get_code->{displayname}->($instance);

  See metadata attribute ui sub-key displayname (below).

description

 type: string

The DESCRIPTION section of the class's POD documentation.

inheritence

 type: array ref

Array of classes from which this class inherits (same as @ISA).

methods

 type: hash ref

A hash containing metadata describing the class's object methods. Functionality not yet implemented.

related_docs

 type: string

The SEE ALSO section of the class's POD documentation.

revision_date

 type: string

The class's revision date, pulled from the DATE section of its POD documentation.

synopsis

 type: string

The SYNOPSIS section of the class's POD documentation.

tangram

 type: hash ref

 { table => 'foo'
   bases => [qw( MyParent )] }

An anonymous hash containing a Class::Tangram-style schema definition [but --without-- a 'fields' key!]. This attribute may be left unset if related features are not needed by the class being set up (like persistence or schema inheritence).

template_filtering

 type: string

Provides control over how template attributes (defined in super classes) are handled for the entity class being established. Available settings:

• accept

  (default) Super class template attributes become defined as native attributes.

• block

  Super class template attributes are ignored.

• passthru

  Super class template attributes remain as template attributes as they are imported from the super class; they exist only as metadata (their metadata is copied verbatim from the super class). As such the template attrbiutes may be considered as simply "passing through" from the super class to any subclasses.

ui

 type: hash ref

Metadata expressing desired default behavior when generating user interfaces for this class. Valid keys are as follows:

• attribute_options

   type: hash ref  [read only]
  
   { hidden => [ 'attr1', 'attr3' ] }

  Hash keys: names of attribute UI metadata options (see options under ui attribute of Myco::Base::Entity::Meta::Attribute). Hash values: reference to an array of entity attributes having the given option set. This will automatically be set up during metadata initialization.

  displayname

   type: string or code ref
  
   sub { $_[0]->get_attr1 . ' ' . $_[0]->get_attr2 }

  The name of an attribute containing values that uniquely describe a given object of this class -or- an anonymous subroutine that, if called as an object method, returns a value that serves the same purpose. This value is used has heading for views of individual objects and in lists of objects (see key list, below).

  list

   type: hash ref
  
   {
     layout => [qw(__DISPLAYNAME__ attr2 attr3)],
   }

  Allows spefication of a display format used by default when objects of this class are displayed in a list. The layout sub-array specifies the entity attributes, and order thereof, used in the listing. An array element containing the string "__DISPLAYNAME__" will result in the list attribute for the given position being populated as directed via the displayname key (above).

  view

   type: hash ref
  
   {
     layout => [qw(attr4 attr3)],
   }

  Allows specification of a display format used by default when an object of this class is viewed. Attributes are displayed in the specified order.

version

 type: string

The class's current version number, pulled from the VERSION section of its POD documentation.

COMMON ENTITY INTERFACE

constructor, accessors, and other methods -- as inherited from Class::Tangram. Persistence related methods do not apply.

ADDED CLASS / INSTANCE METHODS

activate_class

 $metadata->activate_class;

Builds $schema for the entity class that $metadata describes into a Class::Tangram complient schema data structure and then activates it using Myco::Base::Entity::import_schema(). This statement should be placed as the last line in the class's source file.

Additional detail about the entity class is discovered and stored within $metadata. For example, for each entity attribute a closure is created capable of generating an appropriate user interface element for that attribute. (See ...::Meta::Attribute for more detail.)

INSTALLED METHODS

These new methods are installed directly into the described class namespace.

displayname()

An instance method; returns the displayname of the calling entity instance, in accordance with the setting of the displayname class metadata attribute (see ATTBRIBUTES section).

introspect()

Both a class and instance method; returns a reference to the ...::Meta object describing the class.

add_attribute

 $metadata->add_attribute(
   name => 'doneness',
   tangram_options => {required => 1},
   type => 'int',
   synopsis => "How you'd like your meat cooked",
   syntax_msg => "single number: 0 through 5",
   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 => { label => "Cook until..",
           widget => [ 'popup_menu' ] },
 );

Adds a Myco::Base::Entity::Meta::Attribute object containing metadata that describes an attribute. Valid named parameters are as follows:

• name [required]

• readonly

• syntax_msg

• synopsis

• tangram_options

• template

• type [required]

• type_options

• value_labels

• values

• ui

For more detail see ATTRIBUTES section from Myco::Base::Entity::Meta::Attribute

Note: an attribute declared via add_attribute() overrides any same-named attribute declared directly in a $schema data structure.

add_query

 $metadata->add_query( %query_attributes );

Adds a Myco::Base::Entity::Meta::Query object. For more detail see Myco::Base::Entity::Meta::Query

add_virtuals

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::Attribute, Myco::Base::Entity, Myco::Base::Entity::Meta::Test, Myco, Tangram, Class::Tangram, mkentity

cpanm Myco

perl -MCPAN -e shell
install Myco