Rose::HTMLx::Form::Related(3)

NAME
Rose::HTMLx::Form::Related - RHTMLO forms, living together

SYNOPSIS
 package MyForm;
 use strict;
 use parent 'Rose::HTMLx::Form::Related';

 sub init_metadata {
    my $self = shift;
    return $self->metadata_class->new(
        form => $self,
        object_class => 'MyORMClass',
    );
 }

 1;

DESCRIPTION
Rose::HTMLx::Form::Related is a subclass of Rose::HTML::Form. Rose::HTMLx::Form::Related can interrogate the relationships between ORM classes and the Forms that represent them, and use that data to tie multiple Rose::HTMLx::Form::Related classes together.

There are some additional convenience methods provided, as well as the addition to two more field types (boolean and autocomplete) not part of the standard Rose::HTML::Form installation.

METHODS

  init
Overrides base method to call interrelate_fields() if metadata->interrelate_fields() is true.

  init_metadata
Creates and returns a Rose::HTMLx::Form::Related::Metadata object. This method will not be called if a metadata object is passed in new().

  init_metadata_class
Returns name of the metadata class. Default is 'Rose::HTMLx::Form::Related::Metadata'.

  init_app_class
Returns name of class whose instances are stored in app().

Default is the emptry string.

  init_debug
Returns 0 by default, unless the RHTMLO_DEBUG env var is set to a true value.

  object_class
Shortcut to metadata->object_class.

  hidden_to_text_field( hidden_field_object )
Returns a Text field based on hidden_field_object.

  field_names_by_rank
Returns array ref of field names sorted numerically by their rank attribute.

  interrelate_fields( [ N ] )
Called by init() after the SUPER::init() method has been called if the metadata->interrelate_fields boolean is true (the default).

interrelate_fields() will convert fields that return true from metadata->related_field() to menu or autocomplete type fields based on foreign key metadata from metadata->object_class().

In other words, interrelate_fields() will convert your many-to-one foreign-key relationships into HTML fields that help enforce the relationship.

The N argument is the maximum number of values to consider before creating an autocomplete field instead of a menu field. The default is 50, which is a reasonable number of options in a HTML menu.

  get_objects_count( object_class => class_name )
Returns an integer reflecting the number of objects available for iterrelate_fields().

The default is 100 which is useless. You should override this method in your subclass to actually query the db. All counts are memoized internally so get_objects_count() will only ever be called once per class_name.

  get_objects( object_class => foreign_class_name )
Returns an array ref of objects of type foreign_class_name. The array ref is used by interrelate_fields() to auto-populate popup menus.

The default is to return an empty array ref. Override in your subclass to do something more meaningful.

Note that get_objects() will be called by clear() and reset() so that you can cache Form objects and always get up-to-date menu options.

  init_with_object
Overrides base method to always return the Form object that called the method.

  clear
Overrides base method to reset any options in any interrelated menu fields by calling get_objects() again.

  reset
Overrides base method to reset any options in any interrelated menu fields by calling get_objects() again.

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:

•   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>

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.