The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Rose-DBx-Garden-Catalyst-0.08
River stage zero No dependents
++
/ Rose::DBx::Garden::Catalyst

NAME

Rose::DBx::Garden::Catalyst - plant Roses in your Catalyst garden

SYNOPSIS

    # create a Catalyst app
    > catalyst.pl MyApp
        
    # create a Rose::DBx::Garden::Catalyst script
    > cat mk_cat_garden.pl
    use Rose::DBx::Garden::Catalyst;
    use MyDB;  # isa Rose::DB
    
    my $garden = Rose::DBx::Garden::Catalyst->new(
                    catalyst_prefix => 'MyApp',
                    garden_prefix   => 'MyRDBO',
                    db              => MyDB->new,
                    tt              => 1,  # make Template Toolkit files
                    );
                    
    $garden->plant('MyApp/lib');
    
    # run your script
    > perl mk_cat_garden.pl
    
    # start your Catalyst dev server
    > cd MyApp
    > perl script/myapp_server.pl
    
    # enjoy the fruits at http://localhost:3000/rdgc

DESCRIPTION

** DEVELOPMENT RELEASE -- API SUBJECT TO CHANGE **

Rose::DBx::Garden::Catalyst extends Rose::DBx::Garden to create Catalyst components that use the RDBO and RHTMLO classes that the Garden class produces.

By default this class creates stub Template Toolkit files for use with the RDBO and RHTMLO CRUD components. If you use a different templating system, just set the tt option to 0.

METHODS

Only new or overridden methods are documented here.

init_template_class

If the tt config option is true, use the template_class() class for the raw snippets of presentation code. Default is Rose::DBx::Garden::Catalyst::Templates.

init_base_code

Override the base method to create methods useful to RDBO classes used in Catalyst.

init_base_form_class_code

Custom base Form code to implement features that template will require.

Boolean indicating whether the View should provide links to related tables based on RDBO foreign_keys() and relationships().

Default is true.

Boolean indicating whether the YUI datatable matrix 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.

object_class

Should return the name of the object class that this form class represents.

relationships

Returns arrayref of object_class() foreign_keys() and relationships(). These are guaranteed to be unique with regard to name, so any relationships that are merely wrappers that delegate to a foreign_key object are ignored.

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 = \$form->show_related_field_using( 'RDBO::Person', '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.

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, returns undef.

relationship_info( relationship_object [, info_hashref ] )

Returns a hashref of relationship summary information for relationship_object. If info_hashref is used, updates and returns that hashref.

field_names_by_rank

Returns array ref of field names sorted numerically by their rank attribute. The rank is set in Rose::DBx::Garden according to the ordinal position of the corresponding db column.

init_catalyst_prefix

Defaults to 'MyApp'.

plant( path/to/my/catapp )

Override the base method to create Catalyst-related files in addition to the basic Garden files.

make_catalyst( class_names, path )

Does the actual file creation of Catalyst files. Called by plant().

class_names should be a hash ref of RDBO => RHTMLO class names, as returned by Rose::DBx::Garden->plant(). If you have existing RDBO and RHTMLO classes that have namespaces inconsistent with the conventions in Rose::DBx::Garden, they should still work. Just map the RDBO => RHTMLO classes in your class_names hash ref.

AUTHOR

Peter Karman, <karman at cpan.org>

TODO

client-side JS validation

Should be straightforward since the Garden nows puts column-type as xhtml class value.

RDGC tests

Need a way to reliably test the JS.

Optionally show unique column from related tables via FKs when showing relationships. I.e., do not show the literal FK value but a unique value from the table which the FK references.

BUGS

Known issues:

re-running the script fails to pick up all classes

This is due to issues with @INC and how the RDBO Loader requires classes. There is no known workaround at the moment.

javascript required

The TT templates generated depend heavily on the YUI toolkit http://developer.yahoo.com/yui/. Graceful degredation is not implemented as yet.

Please report any bugs or feature requests to bug-rose-dbx-garden-catalyst at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Rose-DBx-Garden-Catalyst. 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::DBx::Garden::Catalyst

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