From: John Napiorkowski Date: Fri, 17 Apr 2015 19:39:53 +0000 (-0500) Subject: getting the docs in shape X-Git-Tag: 5.90089_002~2 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=044e7667c0cb0cd8dac8b33df1d503abdab0d70c getting the docs in shape --- diff --git a/Changes b/Changes index 8fc0fbb..15d3d99 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,6 @@ # This file documents the revision history for Perl extension Catalyst. -5.90089_002 - 2015-04-15 +5.90089_002 - 2015-04-XX - Changed the way we check for presence of Type::Tiny in a test case to be more explicit in the version requirement. Hopefully a fix for reported test fail. @@ -25,7 +25,10 @@ 'response_class_traits' and 'stats_class_traits' which allow you to compose traits for these core Catalyst classes without needing to create subclasses. So in general any request or response trait on CPAN that used 'CatalystX::RoleApplicator' - should now just work with this core feature. + should now just work with this core feature. Note that can also set thse roles + via new configuration keys, 'request_class_traits', 'response_class_traits' + and 'stats_class_traits'. If you use both config at application class methods, they + are combined. - NEW FEATURE: Core concepts from 'CatalystX::ComponentsFromConfig'. You can now setup components directly from configuration. This could save you some effort and creating 'empty' base classes in your Model/View and Controller directories. This @@ -39,6 +42,9 @@ expect arguments (for example calling $c->model('Foo', 1,2,3,4) where Myapp::Model::Foo does not ACCEPT_CONTEXT. Only components that ACCEPT_CONTEXT do anything with passed arguments in $c->controller/view/model. + - Change the way components are setup so that you can now rely on all components + when setting up a component. Previously application scoped components could not + reliably use an existing application scoped component as a dependecy for initialization. 5.90089_001 - 2015-03-26 - New development branch synched with 5.90085. diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm index 545ec83..3b9e975 100644 --- a/lib/Catalyst.pm +++ b/lib/Catalyst.pm @@ -81,8 +81,9 @@ sub _build_request_constructor_args { sub composed_request_class { my $class = shift; + my @traits = (@{$class->request_class_traits||[]}, @{$class->config->{request_class_traits}||[]}); return $class->_composed_request_class || - $class->_composed_request_class(Moose::Util::with_traits($class->request_class, @{$class->request_class_traits||[]})); + $class->_composed_request_class(Moose::Util::with_traits($class->request_class, @traits)); } has response => ( @@ -104,8 +105,9 @@ sub _build_response_constructor_args { sub composed_response_class { my $class = shift; + my @traits = (@{$class->response_class_traits||[]}, @{$class->config->{response_class_traits}||[]}); return $class->_composed_response_class || - $class->_composed_response_class(Moose::Util::with_traits($class->response_class, @{$class->response_class_traits||[]})); + $class->_composed_response_class(Moose::Util::with_traits($class->response_class, @traits)); } has namespace => (is => 'rw'); @@ -147,8 +149,9 @@ __PACKAGE__->stats_class('Catalyst::Stats'); sub composed_stats_class { my $class = shift; + my @traits = (@{$class->stats_class_traits||[]}, @{$class->config->{stats_class_traits}||[]}); return $class->_composed_stats_class || - $class->_composed_stats_class(Moose::Util::with_traits($class->stats_class, @{$class->stats_class_traits||[]})); + $class->_composed_stats_class(Moose::Util::with_traits($class->stats_class, @traits)); } __PACKAGE__->_encode_check(Encode::FB_CROAK | Encode::LEAVE_SRC); @@ -2872,7 +2875,7 @@ sub setup_components { } } -=head2 $app->inject_components($MyApp_Component_name => \%args); +=head2 $app->inject_component($MyApp_Component_name => \%args); Add a component that is injected at setup: @@ -4128,6 +4131,55 @@ C - See L. C - See L. +=item * + +C + +An arrayref of Ls that get componsed into your stats class. + +=item * + +C + +An arrayref of Ls that get componsed into your request class. + +=item * + +C + +An arrayref of Ls that get componsed into your response class. + +=item * + +C + +A Hashref of L subclasses that are 'injected' into configuration. +For example: + + MyApp->config({ + inject_components => { + 'Controller::Err' => { from_component => 'Local::Controller::Errors' }, + 'Model::Zoo' => { from_component => 'Local::Model::Foo' }, + 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] }, + }, + 'Controller::Err' => { a => 100, b=>200, namespace=>'error' }, + 'Model::Zoo' => { a => 2 }, + 'Model::Foo' => { a => 100 }, + }); + +Generally L looks for components in your Model/View or Controller directories. +However for cases when you which to use an existing component and you don't need any +customization (where for when you can apply a role to customize it) you may inject those +components into your application. Please note any configuration should be done 'in the +normal way', with a key under configuration named after the component affix, as in the +above example. + +Using this type of injection allows you to construct significant amounts of your application +with only configuration!. This may or may not lead to increased code understanding. + +Please not you may also call the ->inject_components application method as well, although +you must do so BEFORE setup. + =back =head1 EXCEPTIONS diff --git a/lib/Catalyst/Delta.pod b/lib/Catalyst/Delta.pod index e965025..76d8cf7 100755 --- a/lib/Catalyst/Delta.pod +++ b/lib/Catalyst/Delta.pod @@ -29,6 +29,31 @@ See L for more. L has a new method 'inject_component' which works the same as the method of the same name in L. +=head2 inject_components + +New configuration key allows you to inject components directly into your application without +any subclasses. For example: + + MyApp->config({ + inject_components => { + 'Controller::Err' => { from_component => 'Local::Controller::Errors' }, + 'Model::Zoo' => { from_component => 'Local::Model::Foo' }, + 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] }, + }, + 'Controller::Err' => { a => 100, b=>200, namespace=>'error' }, + 'Model::Zoo' => { a => 2 }, + 'Model::Foo' => { a => 100 }, + }); + +Injected components are useful to reduce the ammount of nearly empty boilerplate classes +you might have, particularly when first starting an application. + +=head2 Component setup changes. + +Previously you could not depend on an application scoped component doing setup_components +since components were setup 'in order'. Now all components are first registered and then +setup, so you can now reliably use any component doing setup_components. + =head2 VERSION 5.90080+ The biggest change in this release is that UTF8 encoding is now enabled by diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index 6012f98..0d1a60b 100644 --- a/lib/Catalyst/Upgrading.pod +++ b/lib/Catalyst/Upgrading.pod @@ -63,16 +63,25 @@ In L: MyApp->config( 'Model::MyClass' => { - class => + class => 'MyClass', + args => { %args }, }); - - class My::Class - - some param - - +and now in core: + + MyApp->config( + inject_components => { + 'Model::MyClass' => { from_component => 'My::Class' }, + }, + 'Model::MyClass' => { + %args + }, + ); + +Although the cored behavior requires more code, its better separates concerns +as well as plays more into core Catalyst expections of how configuration shoul +look. Also we added a new develop console mode only warning when you call a component with arguments that don't expect or do anything meaningful with those args. Its