[Catalyst-commits] r6297 - trunk/Catalyst-Controller-PathArgs/lib/Catalyst/Controller

[zby at dev.catalyst.perl.org]

Author: zby
Date: 2007-04-18 15:28:05 +0100 (Wed, 18 Apr 2007)
New Revision: 6297

Modified:
   trunk/Catalyst-Controller-PathArgs/lib/Catalyst/Controller/PathArgs.pm
Log:
Some documentation added.


Modified: trunk/Catalyst-Controller-PathArgs/lib/Catalyst/Controller/PathArgs.pm
===================================================================
--- trunk/Catalyst-Controller-PathArgs/lib/Catalyst/Controller/PathArgs.pm	2007-04-18 12:41:13 UTC (rev 6296)
+++ trunk/Catalyst-Controller-PathArgs/lib/Catalyst/Controller/PathArgs.pm	2007-04-18 14:28:05 UTC (rev 6297)
@@ -5,24 +5,7 @@
 
 our $VERSION = '0.1';
 
-#################### subroutine header begin ####################
 
-=head2 sample_function
-
- Usage     : How to use this function/method
- Purpose   : What it does
- Returns   : What it returns
- Argument  : What it wants to know
- Throws    : Exceptions and other anomolies
- Comment   : This is a sample subroutine header.
-           : It is polite to include more pod and fewer comments.
-
-See Also   : 
-
-=cut
-
-#################### subroutine header end ####################
-
 sub create_action {
     my $self = shift;
     my %args = @_;
@@ -40,33 +23,65 @@
 
 
 #################### main pod documentation begin ###################
-## Below is the stub of documentation for your module. 
-## You better edit it!
 
 
 =head1 NAME
 
-Catalyst::Controller::PathArgs - Module abstract (<= 44 characters) goes here
+Catalyst::Controller::PathArgs - syntactic sugar for
+L<Catalyst::DispatchType::Chained>.
 
 =head1 SYNOPSIS
 
+  package MyApp::Controller::Root;
+  use base 'Catalyst::Controller::PathArgs';
+  __PACKAGE__->config->{namespace} = '';
+
+  sub pathargsroot : PathArgs(1) {}
+  
   use Catalyst::Controller::PathArgs;
-  blah blah blah
+  package TestApp::Controller::Pathargsroot;
 
+  use base 'Catalyst::Controller::PathArgs';
 
+
+  sub pathargsend : PathArgs(1) EndPoint { }
+
 =head1 DESCRIPTION
 
-Stub documentation for this module was created by ExtUtils::ModuleMaker.
-It looks like the author of the extension was negligent enough
-to leave the stub unedited.
+This Catalyst Controller base adds two new action attributes: PathArgs (taking
+one numerical argument) and EndPoint.  This is entirely syntactic sugar over
+the L<Catalyst::DispatchType::Chained> full machinery for paths like
+'/book/$book_id/edition/$edition_id/view' - with PathArgs you can chain the
+'book', 'edition' and 'view' methods and declare how many parameters they take.
+EndPoint is needed to declare an ation as the end of the chain (in theory this
+should be computable - but for now I don't see any easy way to do that).
 
-Blah blah blah.
+To declare that the book subroutine is the root chained action with one argument you
+need to declare it in the Root controller with:
 
+  sub book : PathArgs(1) {
 
-=head1 USAGE
+If we had a non chained path with /book/edition - the edition sub would be
+declared in the 'Book' controller - and this is the same case here - you just
+add PathArgs(1) to indicate that it is indeed chained and that it takes one
+parameter. So in the Book controller you add: 
 
+  sub edition : PathArgs(1) {
 
+For the last action in the chain you need to add EndPoint.  So in the
+Book::Edition controller you would need: 
 
+  sub view : PathArgs(0) EndPoint {
+
+Internally PathArgs and EndPoint are converted to 'Chained(.)' and appriopriate 
+CaptureArgs or Args attributes.  For more sophisticated chaining you might need
+to use L<Catalyst::DispatchType::Chained> directly.
+
+=head2 create_action
+
+This is the overriden method from Catalyst::Controller used here to compute the
+new attributes. 
+
 =head1 BUGS
 
 
@@ -77,11 +92,9 @@
 
 =head1 AUTHOR
 
-    HASH(0x60d210)
-    CPAN ID: MODAUTHOR
-    XYZ Corp.
-    a.u.thor at a.galaxy.far.far.away
-    http://a.galaxy.far.far.away/modules
+    Zbigniew Lukasiak
+    CPAN ID: ZBY 
+    http://perlalchemy.blogspot.com/
 
 =head1 COPYRIGHT
 
@@ -94,7 +107,7 @@
 
 =head1 SEE ALSO
 
-perl(1).
+L<Catalyst::DispatchType::Chained>
 
 =cut
 
@@ -102,5 +115,4 @@
 
 
 1;
-# The preceding line will help the module return a true value