rah. rename everything.

[catagits/Catalyst-Runtime.git] / lib / Catalyst / Manual / Intro.pod

diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod
index 314ced4..21a701d 100644 (file)
--- a/lib/Catalyst/Manual/Intro.pod
+++ b/lib/Catalyst/Manual/Intro.pod
@@ -349,12 +349,8 @@ this:
     }
     1;
 
-
 =back
 
-For most applications, Catalyst requires you to define only one config
-parameter:
-
 =head4 Action types
 
 Catalyst supports several types of actions:
@@ -421,6 +417,91 @@ C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
 arguments at the end of your URL, you must use regex action keys. See
 L</URL Path Handling> below.
 
+=item * B<Chained>
+
+    sub section :PathPart('section') :Chained('/') :Captures(1) { }
+
+Chained is a powerful way to handle canonical URIs of the form
+C<http://localhost:3000/section/1/item/2>. Using this URI as an example,
+in Controller::Root you can do the following:
+
+  sub section_handler :PathPart('section') :Chained('/') :Captures(1) {
+      my ( $self, $c ) = @_;
+      $c->stash->{'section'} =
+        $c->Model('Sections')->find($c->req->captures->[0]);
+  }
+
+  sub item_handler :PathPart('item') :Chained('/section_handler') :Args(1) {
+      my ( $self, $c ) = @_;
+      $c->stash->{'item'} =
+        $c->stash->{'section'}->find_related('item',$c->args->[0]);
+  }
+
+The subroutine C<section_handler> matches the path segment "section" as
+a child of "/". It then takes the next path segment, as referenced by
+C<:Captures(1)>, and stashes it in the arrayref
+C<$c-E<gt>req-E<gt>captures>. Since there is also a child of this
+handler, it also gets run, functioning in the same way. However, the
+C<item_handler> subroutine has the C<Args> attribute which means this
+particular routine will only run if there is exactly one argument. See
+L</Args> below for more options.
+
+A parent action can be in any controller or namespace.  
+
+Multiple actions can specify the same parent action in their C<Chained>;
+that is, one action can have multiple children.
+
+=item Chained('xyz')
+
+The action of the parent. For instance, if you have a method
+C<item_handler> in the controller C<SuperMarket::Aisle>, the action
+would be C</supermarket/aisle/item_handler>. For a Root handler this
+would be '/'. For an action in the same controller namespace you can use
+a relative name like C<:Chained('foo')>.
+
+=item PathPart('xyz')
+
+The name of this path section in the Chained tree mapping to the URI. If
+you specify C<:PathPart> without arguments, it takes the name of the
+action specifying the argument.  For example, these two declarations
+have the same effect:
+
+  sub foo :PathPart('foo') :Chained('bar') :Args(1) {
+      ...
+  }
+
+and
+
+  sub foo :PathPart :Chained('bar') :Args(1) {
+      ...
+  }
+
+The value can also contain a slash, for example:
+
+  sub baz :PathPart('bar/baz') :Chained('/') :Captures(1) {
+      ...
+  }
+
+would be involved in matches on C</bar/baz/*/...> paths.
+
+=item Captures(integer)
+
+Will 'collapse' the next C<integer> path segments in the request URI and
+push them into the arrayref C<$c-E<gt>req-E<gt>captures>. An action
+specifying C<Captures> is thought to be used as target for C<Chained>
+specifications. Also see the C<Args> attribute below, which is used for
+endpoints.
+
+=item Args(int)
+
+The number of path segments to capture at the end of a request URI. This
+B<must> be included in your leaf nodes. You can use C<Args(0)> for an
+equivalent of the index action.  Args with no parameters will capture
+every postfixed segment into C<$c-E<gt>req-E<gt>args>.
+
+A specification of C<Args> is seen as endpoint in regard to an additional
+C<Chained> specification.
+
 =item * B<Top-level> (B<Global>)
 
     package MyApp::Controller::Foo;
@@ -480,10 +561,6 @@ would match any URL starting /foo/bar/. To restrict this you can do
 
 to only match /foo/bar/*/
 
-=item * B<PathPart>, B<Captures> and B<ChildOf>
-
-Matt is an idiot and hasn't documented this yet.
-
 =back
 
 B<Note:> After seeing these examples, you probably wonder what the point