Peter Karman > Rose-HTMLx-Form-Related-0.22 > Rose::HTMLx::Form::Related::Metadata

Download:
Rose-HTMLx-Form-Related-0.22.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.22   Source   Latest Release: Rose-HTMLx-Form-Related-0.24

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.

related_field_names([array_ref])

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

related_fields( [hash_ref] )

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.

show_related_fields

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

Default is true.

show_related_values

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

init_default_related_sort_by

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.

init_related_field_map

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.

is_related_field( field_name )

Returns true if field_name is a related_field().

related_field( field_name )

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.

show_related_field_using( foreign_object_class, 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.

syntax highlighting: