[Catalyst-commits] r10219 - in Catalyst-Runtime/5.80/trunk: . lib/Catalyst

[t0m at dev.catalyst.perl.org]

Author: t0m
Date: 2009-05-21 13:45:55 +0000 (Thu, 21 May 2009)
New Revision: 10219

Modified:
   Catalyst-Runtime/5.80/trunk/Changes
   Catalyst-Runtime/5.80/trunk/lib/Catalyst/Upgrading.pod
Log:
Doc clarification, domm++

Modified: Catalyst-Runtime/5.80/trunk/Changes
===================================================================
--- Catalyst-Runtime/5.80/trunk/Changes	2009-05-21 13:44:58 UTC (rev 10218)
+++ Catalyst-Runtime/5.80/trunk/Changes	2009-05-21 13:45:55 UTC (rev 10219)
@@ -1,5 +1,6 @@
 # This file documents the revision history for Perl extension Catalyst.
 
+        - Clarify correct techniques for Moose controllers (domm)
         - Add $c->req->remote_user to disambiguate from $c->req->user (dwc)
 
 5.80004 2009-05-18 17:03:23

Modified: Catalyst-Runtime/5.80/trunk/lib/Catalyst/Upgrading.pod
===================================================================
--- Catalyst-Runtime/5.80/trunk/lib/Catalyst/Upgrading.pod	2009-05-21 13:44:58 UTC (rev 10218)
+++ Catalyst-Runtime/5.80/trunk/lib/Catalyst/Upgrading.pod	2009-05-21 13:45:55 UTC (rev 10219)
@@ -34,6 +34,17 @@
 
 Declaring actions in Roles is currently unsupported.
 
+=head2 Using Moose in Components
+
+The correct way to use Moose in a component in a both forward and backwards
+compatible way is:
+
+    package TestApp::Controller::Root;
+    use Moose;
+    BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
+
+See L<Components which inherit from Moose::Object before Catalyst::Component>.
+
 =head1 Known backwards compatibility breakages
 
 =head2 Applications in a single file
@@ -104,21 +115,6 @@
 C<Catalyst::Component> inherits from C<Moose::Object>, and so C< @ISA > fails
 to linearize.
 
-The fix for this is to not inherit directly from C<Moose::Object>
-yourself. Having components which do not inherit their constructor from
-C<Catalyst::Component> is B<unsupported>, and has never been recommended,
-therefore you're on your own if you're using this technique. You'll need
-to detect the version of Catalyst your application is running, and deal
-with it appropriately.
-
-You will also see this issue if you do the following:
-
-    package TestApp::Controller::Example;
-    use Moose;
-    use base 'Catalyst::Controller';
-
-as C< use base > appends to @ISA.
-
 The correct way to use Moose in a component in a both forward and backwards
 compatible way is:
 
@@ -129,6 +125,13 @@
 Note that the C< extends > declaration needs to occur in a begin block for
 L<attributes> to operate correctly.
 
+This way you do not inherit directly from C<Moose::Object>
+yourself. Having components which do not inherit their constructor from
+C<Catalyst::Component> is B<unsupported>, and has never been recommended,
+therefore you're on your own if you're using this technique. You'll need
+to detect the version of Catalyst your application is running, and deal
+with it appropriately.
+
 You also don't get the L<Moose::Object> constructor, and therefore attribute
 initialization will not work as normally expected. If you want to use Moose
 attributes, then they need to be made lazy to correctly initialize.
@@ -140,6 +143,14 @@
 
 If you depend on Catalyst 5.8, then B<all> Moose features work as expected.
 
+You will also see this issue if you do the following:
+
+    package TestApp::Controller::Example;
+    use Moose;
+    use base 'Catalyst::Controller';
+
+as C< use base > appends to @ISA.
+
 =head3 use Moose in MyApp
 
 Similar to the above, this will also fail: