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_nameExample: 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::ResultRolesA 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.