[Catalyst-commits] r6948 - trunk/Catalyst-Manual/lib/Catalyst/Manual

[jrockway at dev.catalyst.perl.org]

Author: jrockway
Date: 2007-09-27 08:59:31 +0100 (Thu, 27 Sep 2007)
New Revision: 6948

Modified:
   trunk/Catalyst-Manual/lib/Catalyst/Manual/ExtendingCatalyst.pod
Log:
add explanation of CatalystX:: to manual; cleanup ExtendingCatalyst a bit

Modified: trunk/Catalyst-Manual/lib/Catalyst/Manual/ExtendingCatalyst.pod
===================================================================
--- trunk/Catalyst-Manual/lib/Catalyst/Manual/ExtendingCatalyst.pod	2007-09-27 00:43:31 UTC (rev 6947)
+++ trunk/Catalyst-Manual/lib/Catalyst/Manual/ExtendingCatalyst.pod	2007-09-27 07:59:31 UTC (rev 6948)
@@ -46,11 +46,15 @@
 
 =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,6 +93,16 @@
 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.
+
 =head2 Inheritance and overriding methods
 
 While Catalyst itself is still based on L<NEXT> (for multiple
@@ -126,6 +140,10 @@
 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
@@ -589,8 +607,10 @@
 
 =head1 AUTHOR
 
-Robert Sedlacek C<rs at 474.at>
+Robert Sedlacek C<< <rs at 474.at> >>
 
+Jonathan Rockway C<< <jrockway at cpan.org> >>
+
 =head1 LICENSE AND COPYRIGHT
 
 This document is free, you can redistribute it and/or modify it under