X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCatalystAndMoose.pod;h=a4a49fea9af5638478aafc5d6e09eac351da3509;hp=84ca1335bfdaab537c5c9d06bcb1c5767947c953;hb=ad60b48b6c58a60d421aaa9caa580480c36528d8;hpb=f68b710f44808db5684c6346779080d35896346a diff --git a/lib/Catalyst/Manual/CatalystAndMoose.pod b/lib/Catalyst/Manual/CatalystAndMoose.pod index 84ca133..a4a49fe 100644 --- a/lib/Catalyst/Manual/CatalystAndMoose.pod +++ b/lib/Catalyst/Manual/CatalystAndMoose.pod @@ -2,15 +2,14 @@ Catalyst::Manual::CatalystAndMoose - How Catalyst 5.8+ and Moose relate - =head1 DESCRIPTION -Since version 5.8 the core of Catalyst is based on L. Although -the developers went through great lengths to allow for a seamless -transition, there are still a few things to keep in mind when trying +Since version 5.8 the core of Catalyst is based on L. Although +the developers went through great lengths to allow for a seamless +transition, there are still a few things to keep in mind when trying to exploit the power of L in your Catalyst application. -This document provides you with a short overview of common caveats and +This document provides you with a short overview of common caveats and best practices to use L-based classes within Catalyst. @@ -19,43 +18,47 @@ best practices to use L-based classes within Catalyst. A Moose-ified version of the context class should look like this: package MyApp; - + use Moose; use namespace::autoclean; use Catalyst ( # your roles and plugins ); - + extends 'Catalyst'; + + # If you want to use method modifiers to adjust the setup process, (e.g. setup_finalize) + # they must be here, before the call to setup (advanced users only) + $app->config( name => 'MyApp' ); $app->setup; - - # method modifiers must be created after setup because otherwise they will + + # method modifiers generally must be created after setup because otherwise they will # conflict with plugin overrides - + after 'finalize' => sub{ my $c = shift; $c->log->info( 'done!' ); } -You should also be aware, that roles in C<< $c-Esetup >> are applied -after the last plugin with all the benefits of using a single -C<< with() >> statement in an ordinary L class. +You should also be aware, that roles in C<< $c-Esetup >> are applied +after the last plugin with all the benefits of using a single +L statement in an ordinary L class. -Your class is automatically made immutable at the end of the current file. +Your class is automatically made immutable at the end of the current file. -CAVEAT: Using roles in C<< $c-Esetup >> was implemented in Catalyst +CAVEAT: Using roles in C<< $c-Esetup >> was implemented in Catalyst version 5.80004. In prior versions you might get away with after 'setup_plugins' => sub{ with( # your roles )}; - + $app->setup( # your plugins ); -but this is discouraged and you should upgrade to 5.80004 anyway, -because it fixes a few important regression against 5.71 +but this is discouraged and you should upgrade to 5.80004 anyway, +because it fixes a few important regressions against 5.71 CAVEAT: Using roles in C<< $c-Esetup >> will not currently allow you to pass parameters to roles, or perform conflict resolution. @@ -64,29 +67,28 @@ Conflict detection still works as expected. =head2 ACCESSORS -Most of the request-specific attributes like C<$c-Estash>, -C<$c-Erequest> and C<$c-Eresponse> have been converted to -L attributes but without type constraints, attribute helpers or -builder methods. This ensures that Catalyst 5.8 is fully backwards -compatible to applications using the published API of Catalyst 5.7 but -slightly limits the gains that could be had by wielding the full power +Most of the request-specific attributes like C<$c-Estash>, +C<$c-Erequest> and C<$c-Eresponse> have been converted to +L attributes but without type constraints, attribute helpers or +builder methods. This ensures that Catalyst 5.8 is fully backwards +compatible to applications using the published API of Catalyst 5.7 but +slightly limits the gains that could be had by wielding the full power of L attributes. -Most of the accessors to information gathered during compile time is -managed by C, which is a L-aware version -of L but not compatible with +Most of the accessors to information gathered during compile time is +managed by C, which is a L-aware version +of L but not compatible with L. - =head2 ROLES AND METHOD MODIFIERS -Since the release of Catalyst version 5.8 the only reason for creating -a Catalyst extension as a plugin is to provide backward compatibility +Since the release of Catalyst version 5.8, the only reason for creating +a Catalyst extension as a plugin is to provide backward compatibility to applications still using version 5.7. -If backward compatibility is of no concern to you, you could as easily -rewrite your plugins as roles and enjoy all the benefits of automatic -method re-dispatching of C<< before >> and C<< after >> method +If backward compatibility is of no concern to you, you could as easily +rewrite your plugins as roles and enjoy all the benefits of automatic +method re-dispatching of C<< before >> and C<< after >> method modifiers, naming conflict detecting and generally cleaner code. Plugins and roles should never use @@ -97,17 +99,16 @@ but rely on after 'setup_finalize' => sub { ... } # this will work -to run their own setup code if needed. If they need to influence the -setup process itself, they can modify C<< setup_dispatcher() >>, -C<< setup_engine() >>, C<< setup_stats() >>, C<< setup_components() >> -and C<< setup_actions() >>, but this should be done with due +to run their own setup code if needed. If they need to influence the +setup process itself, they can modify C<< setup_dispatcher() >>, +C<< setup_engine() >>, C<< setup_stats() >>, C<< setup_components() >> +and C<< setup_actions() >>, but this should be done with due consideration and as late as possible. - =head1 CONTROLLERS -To activate Catalyst's action attributes, Moose-ified controller -classes need to extend L at compile time before +To activate Catalyst's action attributes, Moose-ified controller +classes need to extend L at compile time before the actions themselves are declared: package Catalyst::Controller::Root; @@ -115,11 +116,10 @@ the actions themselves are declared: use namespace::autoclean; BEGIN { extends 'Catalyst::Controller'; } - with qw( + with qw( # your controller roles ); - =head2 Controller Roles It is possible to use roles to apply method modifiers on controller actions