/ 
Rose-HTMLx-Form-Related-0.24
River stage one • 2 direct dependents • 2 total dependents
/ Rose::HTMLx::Form::Related::Metadata

NAME

Rose::HTMLx::Form::Related::Metadata - RHTMLO Form class metadata

DESCRIPTION

Rose::HTMLx::Form::Related::Metadata interrogates and caches interrelationships between Form and ORM classes.

You typically access an instance of this class via the metadata() method in your Form class.

METHODS

init

Overrides base init() method to build metadata.

form( [form] )

Get/set the Rose::HTMLx::Related::Form object.

Get/set the array ref of field names representing foreign keys.

Get/set the hash ref of related field names to RelInfo objects.

relationship_data( [hash_ref] )

Get/set the hash ref of RelInfo objects, keyed by the RelInfo->name value.

Boolean indicating whether the Form should provide links to related forms based on ORM relationships.

Default is true.

Boolean indicating whether the Form should show related unique field values rather than the foreign keys to which they refer.

Default is true.

show_relationships

Boolean indicating whether the View should provide links to related tables based on RDBO relationship method names that do not have corresponding field names.

init_controller_prefix

The default is undef.

init_labels

Should return a hashref of method (field) names to labels. Useful for giving labels to non-fields like relationship names.

init_sort_prefix

Should return a hashref of method (field) names to any strings that should be prefixed to the name for sorting. This is to support (for example) sorts on multi-table joins.

Default is empty hashref.

init_object_class

Should return the name of the ORM object class the Form class represents. Default is the Form class name less the ::Form part.

init_field_uris

Should return a hashref of field name to a URI value.

init_default_sort_by

Should return the name of the field to sort by in (for example) search results.

Default is null (empty string).

Should return the name of the related field to sort by in (for example) search results that join tables.

Default is null (empty string).

init_default_selected

Should return the name of the relationship to show as initially active in an interface.

Default is null (emptry string).

init_takes_object_as_argument

Set hash ref of ORM method names in foreign_class that take the related ORM object as a single argument.

field_uri( field_name )

Returns the value from field_uris() for key field_name if such a key exists. Otherwise, returns undef.

init_field_methods

Returns array of method names to use for rendering form. Default is form->field_names().

You may want to override this value, especially for large forms, in order to show only a subset of the most meaningful field values.

Used by show_related_fields_using(), this method should return a hashref of field_name to method_name where field_name is a field in the Form and method_name is a method name in the foreign object_class.

The default is an empty hashref, which means that show_related_fields_using() will take the first unique column it can find as the method_name.

init_relationships

You may define the Form relationships as an array ref using this method in your subclass, or via the "relationships" key/value pair in new().

If you define this value explicitly, the value must be an array ref of either Rose::HTMLx::Form::Related::RelInfo objects, or hash refs (which will be blessed into Rose::HTMLx::Form::Related::RelInfo objects).

If not defined, discover_relationships() is automatically called internally in new(). The default return value is undef, triggering discover_relationships. You can turn off relationships altogether if you set it to an empty array ref, although that begs the question of why you are using Rose::HTMLx::Form::Related in the first place.

init_relinfo_class

Returns the default value 'Rose::HTMLx::Form::Related::RelInfo'.

discover_relationships

This method must be overriden by model-specific subclasses. The method should interrogate object_class() and set the array ref of relinfo_class() objects via the relationships() mutator method. A Rose::DB::Object-derived object that is a subclass of Rose::DBx::Garden::Catalyst::Object will have a schema_class_prefix method, which is to be used in determining the name of the Controller class associated with related Forms. Specifically, the return value of schema_class_prefix will be stripped from the beginning of the related Form's class name, and will be replaced with the value of controller_prefix if such is defined.

Returns true if field_name is a related_field().

If field_name represents a foreign key or other relationship to a different object class (and hence a different form class), then related_field() will return a hashref with relationship summary information.

If field_name does not represent a related class, will croak.

has_relationship_info( relationship )

Returns true if relationship information is known.

relationship_info( relationship )

Returns the same RelInfo object as related_field(), only using a relationship object or name instead of a field name.

Returns the name of a field to use for display from foreign_object_class based on a relationship using field_name.

This magic is best explained via example. Say you have a 'person' object that is related to a 'user' object. The relationship is defined in the 'user' object as:

person_id => person.id

where the id of the 'person' object is a related (foreign key) to the person_id value of the user object. In a form display for the 'user', you might want to display the name of the 'person' rather than the id, so show_related_field_using() will look up the first unique text field in the foreign_object_class (in this case, the 'person' class) and return that field.

my $field_name = $form->show_related_field_using( 'MyPerson', 'person_id' )

And because it's a method, you can override show_related_field_using() to perform different logic than simply looking up the first unique text key in the foreign_object_class.

If no matching field is found, returns undef.

The default behaviour is to ignore foreign_object_class altogether, deferring to related_field_map() if field_name is defined there and returning undef otherwise.

Override this method in a base class that understands how to interrogate foreign_object_class.

foreign_field_value( field_name, object )

Returns the value from the foreign object related to object for the foreign column related to field_name.

Returns undef if (a) there is no foreign field related to field_name or (b) if there is no foreign object.

Example:

my $username = $form->foreign_field_value( 'email_address', $person );
# $username comes from a $user record related to $person

AUTHOR

Peter Karman, <karman at cpan.org>

BUGS

Please report any bugs or feature requests to bug-rose-htmlx-form-related at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Rose-HTMLx-Form-Related. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Rose::HTMLx::Form::Related

You can also look for information at:

ACKNOWLEDGEMENTS

The Minnesota Supercomputing Institute http://www.msi.umn.edu/ sponsored the development of this software.

COPYRIGHT & LICENSE

Copyright 2008 by the Regents of the University of Minnesota.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.