X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FExtendingCatalyst.pod;h=56e237a37f3044597d063631fb7eebbd4f1495b8;hp=f9506a4258055ef5d4266aae88fb5160951d8462;hb=e12f80114e604748198074c94b9e6408a6bac099;hpb=23cf3a36a43f0eb257f9438491a8444049ebdec8

diff --git a/lib/Catalyst/Manual/ExtendingCatalyst.pod b/lib/Catalyst/Manual/ExtendingCatalyst.pod
index f9506a4..56e237a 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<Moose> 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<Moose::Manual::Roles> 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<not> wrap methods provided by L<Catalyst> until B<after> 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<MooseX::MethodAttributes> 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<Catalyst::Manual::CatalystAndMoose> for specific information
+about using Roles in combination with Catalyst, and L<Moose::Manual::Roles>
+for more information about roles in general.
 
 =head2 Inheritance and overriding methods
 
@@ -255,8 +229,7 @@ action:
 
   sub foo : Local Bar('Baz') {
       my ($self, $c) = @_;
-      my $attributes =
-      $self->action_for('foo')->attributes;
+      my $attributes = $self->action_for('foo')->attributes;
       $c->res->body($attributes->{Bar}[0] );
   }
 
@@ -289,12 +262,17 @@ component configuration.
 
 You are advised to create accessors on your component class for your
 configuration values. This is good practice and makes it easier to
-capture configuration key typos. You can do this with the
-C<mk_ro_accessors> method provided to L<Catalyst::Component> via
-L<Class::Accessor::Fast>:
+capture configuration key typos, or missing keys.
+
+You can do this with L<Moose>:
+
+  package MyApp::Controller::Foo;
+  use Moose;
+  use namespace::autoclean;
+  BEGIN { extends 'Catalyst::Controller' };
+
+  has model_name ( is => 'ro', required => 1 );
 
-  use base 'Catalyst::Controller';
-  __PACKAGE__->mk_ro_accessors('model_name');
   ...
   my $model_name = $controller->model_name;
 
@@ -320,10 +298,10 @@ methods code. You can surround this by overriding the method in a
 subclass:
 
   package Catalyst::Action::MyFoo; 
-  use strict;
-
+  use Moose;
+  use namespace::autoclean;
   use MRO::Compat; 
-  use base 'Catalyst::Action';
+  extends 'Catalyst::Action';
 
   sub execute {
       my $self = shift;
@@ -351,10 +329,10 @@ For example, the action class below will make the action only match on
 Mondays:
 
   package Catalyst::Action::OnlyMondays; 
-  use strict;
-
+  use Moose;
+  use namespace::autoclean;
   use MRO::Compat;
-  use base 'Catalyst::Action';
+  extends 'Catalyst::Action';
 
   sub match {
       my $self = shift;
@@ -374,7 +352,11 @@ If you are using action classes often or have some specific base
 classes that you want to specify more conveniently, you can implement
 a component base class providing an attribute handler.
 
-For further information on action classes, please refer to
+It is not possible to use multiple action classes at once, however
+L<Catalyst::Controller::ActionRole> allows you to apply L<Moose Roles|Moose::Role>
+to actions.
+
+For further information on action classes and roles, please refer to
 L<Catalyst::Action> and L<Catalyst::Manual::Actions>.
 
 =head2 Component base classes
@@ -398,8 +380,10 @@ already provided via the C<+> prefix for action classes. A simple
 
 will use C<MyApp::Action::Bar> as action class.
 
-  package MyApp::Base::Controller::FullClass; use strict; use base
-  'Catalyst::Controller';
+  package MyApp::Base::Controller::FullClass;
+  use Moose;
+  use namespace::autoclean;
+  BEGIN { extends 'Catalyst::Controller'; }
 
   sub _parse_FullClass_attr {
       my ($self, $app_class, $action_name, $value, $attrs) = @_;
@@ -412,8 +396,9 @@ sake. We could use this attribute in a subclass like any other
 Catalyst attribute:
 
   package MyApp::Controller::Foo;
-  use strict;
-  use base 'MyApp::Base::Controller::FullClass';
+  use Moose;
+  use namespace::autoclean;
+  BEGIN { extends 'MyApp::Base::Controller::FullClass'; }
 
   sub foo : Local FullClass('MyApp::Action::Bar') { ... }
 
@@ -430,8 +415,10 @@ controller object, or you can even define Catalyst actions which will
 be inherited by the subclasses. Consider this controller base class:
 
   package MyApp::Base::Controller::ModelBase;
-  use strict;
-  use base 'Catalyst::Controller';
+  use Moose;
+  use namespace::autoclean;
+
+  BEGIN { extends 'Catalyst::Controller'; }
 
   sub list : Chained('base') PathPart('') Args(0) {
       my ($self, $c) = @_;
@@ -439,13 +426,13 @@ be inherited by the subclasses. Consider this controller base class:
       my $condition = $self->{model_search_condition} || {};
       my $attrs = $self->{model_search_attrs} || {};
       $c->stash(rs => $model->search($condition, $attrs);
-      }
+  }
 
   sub load : Chained('base') PathPart('') CaptureArgs(1) {
       my ($self, $c, $id) = @_;
       my $model = $c->model( $self->{model_name} );
       $c->stash(row => $model->find($id));
-      }
+  }
   1;
 
 This example implements two simple actions. The C<list> action chains
@@ -462,8 +449,10 @@ The class above is not very useful on its own, but we can combine it
 with some custom actions by sub-classing it:
 
   package MyApp::Controller::Foo;
-  use strict;
-  use base 'MyApp::Base::Controller::ModelBase';
+  use Moose;
+  use namespace::autoclean;
+  
+  BEGIN { extends 'MyApp::Base::Controller::ModelBase'; }
 
   __PACKAGE__->config( model_name => 'DB::Foo',
                        model_search_condition=> { is_active => 1 },
@@ -530,9 +519,11 @@ generation.
 
 Here is some example code for a fictional view:
 
-  package CatalystX::View::MyView;
-  use strict;
-  use base 'Catalyst::View';
+  package Catalyst::View::MyView;
+  use Moose;
+  use namespace::autoclean;
+  
+  extends 'Catalyst::View';
 
   sub process {
       my ($self, $c) = @_;
@@ -583,7 +574,7 @@ authentication.
 
 B<Please do not> release Catalyst extensions as plugins only to
 provide some functionality application wide. Design it as a controller
-base class or another suiting technique with a smaller scope, so that
+base class or another better suited technique with a smaller scope, so that
 your code only influences those parts of the application where it is
 needed, and namespace clashes and conflicts are ruled out.
 
@@ -623,7 +614,7 @@ A simple example like this is actually better as a L<Moose> role, for example:
 
   package CatalystX::UriforUndefWarning;
   use Moose::Role;
-  use namespace::clean -except => 'meta';
+  use namespace::autoclean;
 
   after 'uri_for' => sub {
     my ($c, $arg) = @_;
@@ -631,6 +622,9 @@ A simple example like this is actually better as a L<Moose> role, for example:
       if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
     return $uri;
   };
+  
+Note that Catalyst will load any Moose Roles in the plugin list,
+and apply them to your application class.
 
 =head2 Factory components with COMPONENT()
 
@@ -649,10 +643,10 @@ your component.
 Here is a stub C<COMPONENT> method:
 
   package CatalystX::Component::Foo;
-  use strict;
-  use base 'Catalyst::Component';
-
-  use MRO::Compat;
+  use Moose;
+  use namespace::autoclean;
+  
+  extends 'Catalyst::Component';
 
   sub COMPONENT {
       my $class = shift;
@@ -678,20 +672,45 @@ expectations on a component.
 For more information, please see
 L<Catalyst::Component/"COMPONENT($c,$arguments)">.
 
+=head2 Applying roles to parts of the framework
+
+L<CatalystX::RoleApplicator> will allow you to apply Roles to
+the following classes:
+
+=over
+
+=item Request
+
+=item Response
+
+=item Engine
+
+=item Dispatcher
+
+=item Stats
+
+=back
+
+These roles can add new methods to these classes, or wrap preexisting methods.
+
+The namespace for roles like this is C<Catalyst::TraitFor::XXX::YYYY>.
+
+For an example of a CPAN component implemented in this manor, see
+L<Catalyst::TraitFor::Request::BrowserDetect>.
+
 =head1 SEE ALSO
 
 L<Catalyst>, L<Catalyst::Manual::Actions>, L<Catalyst::Component>
 
-=head1 AUTHOR
+=head1 AUTHORS
 
-Robert Sedlacek C<< <rs@474.at> >>
+Catalyst Contributors, see Catalyst.pm
 
-Jonathan Rockway C<< <jrockway@cpan.org> >>
+=head1 COPYRIGHT
 
-=head1 LICENSE AND COPYRIGHT
-
-This document is free, you can redistribute it and/or modify it under
+This library is free software. You can redistribute it and/or modify it under
 the same terms as Perl itself.
 
 =cut
 
+