From: Tomas Doran Date: Wed, 27 May 2009 22:40:42 +0000 (+0000) Subject: Munge content into different places, and edits for correctness + best practices X-Git-Tag: v5.8005~131 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=4d719c7eb8dcfd8a4b016574d0f8d61d752ad736 Munge content into different places, and edits for correctness + best practices --- diff --git a/lib/Catalyst/Manual/CatalystAndMoose.pod b/lib/Catalyst/Manual/CatalystAndMoose.pod index d3c2120..53d6a38 100644 --- a/lib/Catalyst/Manual/CatalystAndMoose.pod +++ b/lib/Catalyst/Manual/CatalystAndMoose.pod @@ -21,13 +21,14 @@ A Moose-ified version of the context class should look like this: package MyApp; use Moose; - use Catalyst; - - $app->config( name => 'MyApp' ); - $app->setup( + use namespace::autoclean; + use Catalyst ( # your roles and plugins ); + $app->config( name => 'MyApp' ); + $app->setup; + # method modifiers must be created after setup because otherwise they will # conflict with plugin overrides @@ -38,11 +39,11 @@ A Moose-ified version of the context class should look like this: You should also be aware, that roles in C<< $c->setup >> are applied after the last plugin with all the benefits of using a single C<< -with() >> statement in an ordinary L class and that your class -is automatically made immutable for you after the call to setup -(method modifiers in your class will work, though). +with() >> statement in an ordinary L class. + +Your class is automatically made immutable at the end of the current file. -CAVEAT: using roles in C<< $c->setup >> was implemented in Catalyst +CAVEAT: Using roles in C<< $c->setup >> was implemented in Catalyst version 5.80004. In prior versions you might get away with after 'setup_plugins' => sub{ with( @@ -56,8 +57,9 @@ version 5.80004. In prior versions you might get away with but this is discouraged and you should upgrade to 5.80004 anyway, because it fixes a few important regression against 5.71 -[Q: COULD THIS BE USED TO RESOLVE CONFLICTS IN ROLES?]. - +CAVEAT: Using roles in C<< $c->setup >> will not currently allow +you to pass parameters to roles, or perform conflict resolution. +Conflict detection still works as expected. =head2 ACCESSORS @@ -79,10 +81,7 @@ L. 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 but even then you should -consider building your plugin using L and take advantage of -L instead of -overriding methods to alter Catalyst's request lifecycle behavior. +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 @@ -103,7 +102,6 @@ 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 @@ -111,13 +109,29 @@ classes need to extend L at compile time before the actions themselves are declared: package Catalyst::Controller::Root; - use Moose; - BEGIN{ - extends 'Catalyst::Controller'; - with( + use namespace::autoclean; + + BEGIN { extends 'Catalyst::Controller'; } + with qw( # your controller roles ); - } -[MORE TO BE DONE!] +=head2 Controller Roles + +It is possible to use roles to apply method modifiers on controller actions +from 5.80003 onwards, or use modifiers in actions in your controller classes +themselves. + +It is possible to have action methods with attributes inside Moose roles, using +the trait introduced in L version 0.12, example: + + package MyApp::ControllerRole; + use Moose::Role -traits => 'MethodAttributes'; + use namespace::autoclean; + + sub foo : Local { + my ($self, $c) = @_; + ... + } + diff --git a/lib/Catalyst/Manual/ExtendingCatalyst.pod b/lib/Catalyst/Manual/ExtendingCatalyst.pod index f9506a4..824dafc 100644 --- a/lib/Catalyst/Manual/ExtendingCatalyst.pod +++ b/lib/Catalyst/Manual/ExtendingCatalyst.pod @@ -120,36 +120,10 @@ it's possible to use the composability of L roles, and method modifiers to hook onto to provide functionality. These can be applied to your models/views/controllers, and your application -class. Please see the sections below for special notes and caveats, and -the L for more information about roles in general. - -=head3 In your application class - -It should be noted that when applying roles to your application class, that -you should B wrap methods provided by L until B you have -run C<< __PACKAGE__->setup >>, as your class does not inherit from any of your -plugins until the setup method is run. - -With Catalyst 5.80004, it is possible to include Roles in the plugin list, and -these roles will be applied to your application class immediately after -'traditional' plugins have been composed into your application class' -inheritance hierarchy. - -=head3 In controllers - -Method modifiers on controller actions will work as expected (either in your -controllers, or when composed from roles) in Catalyst 5.80003 and above. - -It is possible to have action methods with attributes inside Moose roles, using -the trait introduced in L version 0.12, example: - - package MyApp::ControllerRole; - use Moose::Role -traits => 'MethodAttributes'; - - sub foo : Local { - my ($self, $c) = @_; - ... - } +class, and shipped to CPAN. +Please see L for specific information +about using Roles in combination with Catalyst, and L +for more information about roles in general. =head2 Inheritance and overriding methods @@ -623,7 +597,7 @@ A simple example like this is actually better as a L role, for example: package CatalystX::UriforUndefWarning; use Moose::Role; - use namespace::clean -except => 'meta'; + use namespace::autoclean; after 'uri_for' => sub { my ($c, $arg) = @_;