The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Catalyst-TraitFor-Model-DBIC-Schema-ResultRoles-0.011
River stage zero No dependents
++
/ Catalyst::TraitFor::Model::DBIC::Schema::ResultRoles

NAME

Catalyst::TraitFor::Model::DBIC::Schema::ResultRoles - Automatically applying Moose Roles to Result-Classes at BUILD time

VERSION

Version 0.0110

SYNOPSIS

In your Catalyst Model (lib/YourApp/Model/YourModel.pm):

        __PACKAGE__->config(
                ...

                traits => "ResultRoles",
        
                ...
        );

OR in your Application main file (lib/YourApp.pm):

        __PACKAGE__->config(
                ...

                "Model::YourModel" => (
                        ...

                        traits => "ResultRoles",

                        ...
                ),
        );

and then, in an appropriate location (lib/YourApp/Schema/ResultRole/YourResult/YourRole.pm):

        package YourApp::Schema::ResultRole::YourResult::YourRole;

        use namespace::autoclean;
        use Moose::Role;

        YourApp::Schema::Result::YourResult->many_to_many(...);
        YourApp::Schema::Result::YourResult->add_column(...);

        sub your_result_sub{
                # do something result specific
        }
        1;

DESCRIPTION

This module is a trait for DBIC based Catalyst models. It hooks to the models BUILD process and appies a set of Moose Roles to each loaded resultclass. This makes it possible to customize the resultclasses without changing the automaticaly created DBIx::Class::Core files. Resultclasses can be customized by creating one or more roles per resultclass. Customized code and automatically created code are clearly seperated.

Because applying roles depends on the presence of a meta-class, this trait only works with "moosified" resultclasses. "Non-moosified" resultclasses are ignored, which makes it possible to use a mixed set of moosified and non-moosified resultclasses.

CONFIGURATION

enabling the traits

See "SYNOPSIS" above or "traits" in Catalyst::Model::DBIC::Schema

creating roles for result classes

Example:

Assumed the application name is "MyApp", and the schema class is "MyApp::Schema". If you want to create a role for "MyApp::Schema::Book",

create lib/MyApp/Schema/ResultRole/Book.pm with the following content:

        package MyApp::Schema::ResultRole::Book::Author;

        use namespace::autoclean;
        use Moose::Role;

        1;

Within this package, MyApp::Schema::Book can be customized with all features provided by Moose::Role. Result-class methods, like "many_to_many" and "has_many" have to be called with the full result-class name.

Assumed there is another result-class named "Author" and a corresponding BookAuthor relation, a many_to_many relation could be defined for MyApp::Schema::Result::Book by editing the role and adding:

        requires qw/book_authors/;
        MyApp::Schema::Result::Book->many_to_many(authors => 'book_authors', 'author');

to MyApp::Schema::ResultRole::Book::Author, after "use Moose::Role", but before "1;"

How does it work:

Without further configuration, the trait will guess the role_location attribute by calling $self->schema_class and appending "::ResultRole".

Example: Assumed the application name is "MyApp", and the schema class is "MyApp::Schema": The result_location will be set to "MyApp::Schema::ResultRole"

Catalyst::TraitFor::Model::DBIC::Schema::Result uses "find_all_modules" in Module::Find to find possible roles for each defined result source. The roles namespace is expected to be:

 $self->role_location . "::". $souce_name

Example: Assumed the application name is "MyApp", the schema class is "MyApp::Schema" and the current source name is "Book": All packages in "MyApp::Schema::ResultRole::Book" are expected to be roles for MyApp::Schema::Result::Book;

Possible roles are applied to the schema class with "apply_all_roles" in Moose::Util.

setting attributes

All attributes can be configured by setting their "config args" within the applications configuration, either in the the applications main file, or in the applications schema class.

Example: Assumed the application name is "MyApp", and the model class is "MyApp::Model::DB": To enable the "debug" flag, either add

 __PACKAGE__->config(
        rr_debug => 1,
 );

to lib/MyApp/Model/DB.pm, or add

 __PACKAGE__->config(
        'Model::DB' =>{
                rr_debug => 1,
        },
 );

to lib/MyApp.pm.

ATTRIBUTES

The following attributes can be customized:

  • role_location

    A String specifying where the trait should look for ResultRoles. Shoud either be something like "YourApp::Schema::ResultRoles" or like "YourApp/Schema/ResultRoles"

    default: $SCHEMA_CLASS::ResultRoles, where $SCHEMA_CLASS is your applications schema class.

    config arg: rr_role_location

  • die

    A Boolean. If set to 1, the trait will die when it encounters non-moose result classes.

    When set to 0, the trait will only die on errors concerning user-generated ResultRoles. Non-moose result classes are ignored.

    default: 0

    config arg: rr_die

  • debug

    A Boolean. If set to 1, the trait will print status and error messages to STERR (unless it has died before)

    default: 0

    config arg: rr_debug

  • quiet

    A Boolean. If set to 0, the trait will print status and error messages to STDOUT (unless it has died or reported to STDERR before)

    default: 0

    config arg: rr_quiet

BUGS

Please report any bugs or feature requests to bug-catalyst-traitfor-model-dbic-schema-resultroles at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-TraitFor-Model-DBIC-Schema-ResultRoles. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

TODO

  • applying roles to ResultSets

  • manually loading roles from other locations than $self->role_location

  • moosify result classes on demand

AUTHOR

Lukas Thiemeier, <lukast at cpan.org>

SUPPORT

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

        perldoc Catalyst::TraitFor::Model::DBIC::Schema::ResultRoles

A public subversion repository is available at: http://svn.thiemeier.net/public/ResultRole

WebSVN is available at http://svn.thiemeier.net/

SEE ALSO

ACKNOWLEDGEMENTS

  • Larry Marso - thanks for the suggestion

LICENSE AND COPYRIGHT

Copyright 2011 Lukas Thiemeier.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.