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

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.

Overrides base init() method to build metadata.

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.

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.

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

The default is undef.

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

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.

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

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

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).

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

Default is null (emptry string).

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

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

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.

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.

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

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.

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.

Returns true if relationship information is known.

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.

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

Peter Karman, <karman at cpan.org>

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.

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

    perldoc Rose::HTMLx::Form::Related

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Rose-HTMLx-Form-Related

* CPAN Ratings

http://cpanratings.perl.org/d/Rose-HTMLx-Form-Related

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-HTMLx-Form-Related

* Search CPAN

http://search.cpan.org/dist/Rose-HTMLx-Form-Related

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

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.