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=fd3ddf5f152d5f60765d2cb0c97ad2ccfad40da8;hp=2602cef1fd2ba9ad6f4787695878837fd5b803f6;hb=709ea2fce465890b806df6320bb96b0f1a7d27ca;hpb=b7c570ac9ac40be5f5e22088823e1180717e0141

diff --git a/lib/Catalyst/Manual/ExtendingCatalyst.pod b/lib/Catalyst/Manual/ExtendingCatalyst.pod
index 2602cef..fd3ddf5 100644
--- a/lib/Catalyst/Manual/ExtendingCatalyst.pod
+++ b/lib/Catalyst/Manual/ExtendingCatalyst.pod
@@ -46,11 +46,15 @@ forward to L</Namespaces>.
 
 =item Use the C<CatalystX::*> namespace if you can!
 
-Excluding plugins and of course your C<MyApp> code. B<Mind the X!>
+If your extension isn't a Model, View, Controller, Plugin, or Engine,
+it's best to leave it out of the C<Catalyst::> namespace.  Use
+<CatalystX::> instead.
 
 =item Don't make it a plugin unless you have to!
 
-A plugin should be careful as it declares in global namespace.
+A plugin should be careful since it's overriding Catalyst internals.
+If your plugin doesn't really need to muck with the internals, make it a
+base Controller or Model.
 
 =item There's a community. Use it!
 
@@ -89,12 +93,25 @@ putting it in your C<MyApp::*> namespace. Just don't put it in
 C<Model>, C<Controller> or C<View>, because that would make Catalyst
 try to load them as components.
 
+Writing a generic component that only works with Catalyst is wasteful
+of your time.  Try writing a plain perl module, and then a small bit
+of glue that integrates it with Catalyst.  See
+L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> for a
+module that takes the approach.  The advantage here is that your
+"Catalyst" DBIC schema works perfectly outside of Catalyst, making
+testing (and command-line scripts) a breeze.  The actual Catalyst
+Model is just a few lines of glue that makes working with the schema
+convenient.
+
+If you want the thinnest interface possible, take a look at
+L<Catalyst::Model::Adaptor|Catalyst::Model::Adaptor>.
+
 =head2 Inheritance and overriding methods
 
 While Catalyst itself is still based on L<NEXT> (for multiple
 inheritance), extension developers are encouraged to use L<Class::C3>,
-which is what Catalyst will be switching to in some point in the
-future.
+via MRO::Compat, which is what Catalyst will be switching to in the 
+5.80 release.
 
 When overriding a method, keep in mind that some day additionally
 arguments may be provided to the method, if the last parameter is not
@@ -102,7 +119,7 @@ a flat list. It is thus better to override a method by shifting the
 invocant off of C<@_> and assign the rest of the used arguments, so
 you can pass your complete arguments to the original method via C<@_>:
 
-  use Class::C3; ...
+  use MRO::Compat; ...
 
   sub foo { my $self = shift;
             my ($bar, $baz) = @_; # ...  return
@@ -126,6 +143,10 @@ module.  It also shows that you care for your users. If you would like
 your module to become a recommended addition, these things will prove
 invaluable.
 
+If you're just getting started, try using
+L<CatalystX::Starter|CatalystX::Starter> to generate some example
+tests for your module.
+
 =head2 Maintenance
 
 In planning to release a module to the community (Catalyst or CPAN and
@@ -256,9 +277,11 @@ method. The execute method of the action will naturally call the
 methods code. You can surround this by overriding the method in a
 subclass:
 
-  package Catalyst::Action::MyFoo; use strict;
+  package Catalyst::Action::MyFoo; 
+  use strict;
 
-  use Class::C3; use base 'Catalyst::Action';
+  use MRO::Compat; 
+  use base 'Catalyst::Action';
 
   sub execute {
       my $self = shift;
@@ -270,8 +293,10 @@ subclass:
   }
   1;
 
-We are using L<Class::C3> to re-dispatch to the original C<execute> method
-in the L<Catalyst::Action> class.
+We are using L<MRO::Compat> to ensure that you have the next::method
+call, from L<Class::C3> (in older perls), or natively (if you are using 
+perl 5.10) to re-dispatch to the original C<execute> method in the 
+L<Catalyst::Action> class.
 
 The Catalyst dispatcher handles an incoming request and, depending
 upon the dispatch type, will call the appropriate target or chain. 
@@ -285,7 +310,7 @@ Mondays:
 
   package Catalyst::Action::OnlyMondays; use strict;
 
-  use Class::C3;
+  use MRO::Compat;
   use base 'Catalyst::Action';
 
   sub match {
@@ -527,7 +552,7 @@ implementation (excuse the lame class name, it's just an example):
 
   package Catalyst::Plugin::UriforUndefWarning;
   use strict;
-  use Class::C3;
+  use MRO::Compat;
 
   sub uri_for {
       my $c = shift;
@@ -552,8 +577,9 @@ C<config>uration with the application wide overrides and call the
 class' C<new> method to return the component object.
 
 You can override this method and do and return whatever you want.
-However, you should use L<Class::C3> to forward to the original
-C<COMPONENT> method to merge the configuration of your component.
+However, you should use L<Class::C3> (via L<MRO::Compat>) to forward 
+to the original C<COMPONENT> method to merge the configuration of 
+your component.
 
 Here is a stub C<COMPONENT> method:
 
@@ -561,7 +587,7 @@ Here is a stub C<COMPONENT> method:
   use strict;
   use base 'Catalyst::Component';
 
-  use Class::C3;
+  use MRO::Compat;
 
   sub COMPONENT {
       my $class = shift;
@@ -589,7 +615,9 @@ L<Catalyst>, L<Catalyst::Manual::Actions>, L<Catalyst::Component>
 
 =head1 AUTHOR
 
-Robert Sedlacek C<rs@474.at>
+Robert Sedlacek C<< <rs@474.at> >>
+
+Jonathan Rockway C<< <jrockway@cpan.org> >>
 
 =head1 LICENSE AND COPYRIGHT