NAME

Myco::Entity::Meta

meta data container for Myco entity classes

SYNOPSIS

#### Entity class definition

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

# Constructor
my $metadata = Myco::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

Myco::Entity::Meta, as a companion to Myco::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, Myco::Entity::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 Myco::Entity::Meta may be added with just these modifications:

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

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

2. Remove this existing statement:

Myco::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::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::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.

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::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::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::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::Entity::Meta::Query object. For more detail see Myco::Entity::Meta::Query and Myco::QueryTemplate

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Upgrading existing classes

ATTRIBUTES

name

abstract

access_list

attributes

queries

code

description

inheritence

methods

related_docs

revision_date

synopsis

tangram

template_filtering

ui

COMMON ENTITY INTERFACE

ADDED CLASS / INSTANCE METHODS

activate_class

add_attribute

add_query

add_virtuals

LICENSE AND COPYRIGHT

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

Upgrading existing classes

ATTRIBUTES

name

abstract

access_list

attributes

queries

code

description

inheritence

methods

related_docs

revision_date

synopsis

tangram

template_filtering

ui

COMMON ENTITY INTERFACE

ADDED CLASS / INSTANCE METHODS

activate_class

add_attribute

add_query

add_virtuals

LICENSE AND COPYRIGHT

SEE ALSO

Module Install Instructions