From: Nilson Santos Figueiredo Júnior <nilsonsfj@cpan.org>
Date: Fri, 6 Feb 2009 02:24:24 +0000 (+0000)
Subject: Update docs
X-Git-Tag: 0.07_01~35
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=532f3bcfb201047bdcce21de7a97a32f023248b5;hp=3c5cb6d61dc75101ce515fde5dd66010cb1feeaf;p=catagits%2FCatalyst-View-Component-SubInclude.git

Update docs
---

diff --git a/lib/Catalyst/View/Component/SubInclude/ESI.pm b/lib/Catalyst/View/Component/SubInclude/ESI.pm
index e8f446f..635d978 100644
--- a/lib/Catalyst/View/Component/SubInclude/ESI.pm
+++ b/lib/Catalyst/View/Component/SubInclude/ESI.pm
@@ -39,11 +39,13 @@ uses of includes.
 
 =head1 CLASS METHODS
 
-=head2 C<generate_subinclude( $c, @args )>
+=head2 C<generate_subinclude( $c, $path, @args )>
 
-This will roughly translate to the following code:
+Note that C<$path> should be the private action path - translation to the public
+path is handled internally. After translation, this will roughly translate to 
+the following code:
 
-  my $url = $c->uri_for( @args );
+  my $url = $c->uri_for( $translated_path, @args )->path_query;
   return '<!--esi <esi:include src="$url" /> -->';
 
 Notice that the stash will always be empty. This behavior could be configurable
diff --git a/lib/Catalyst/View/Component/SubInclude/SubRequest.pm b/lib/Catalyst/View/Component/SubInclude/SubRequest.pm
index 982c0a6..baedb69 100644
--- a/lib/Catalyst/View/Component/SubInclude/SubRequest.pm
+++ b/lib/Catalyst/View/Component/SubInclude/SubRequest.pm
@@ -55,13 +55,17 @@ It requires L<Catalyst::Plugin::SubRequest>.
 
 =head2 C<generate_subinclude( $c, $path, @args )>
 
-This will translate to the following sub-request call:
+This will make a sub-request call to the action specified by C<$path>. Note that
+C<$path> should be the private action path - translation to the public path is
+handled internally.
 
-  $c->sub_request( $path, {}, @args );
+So, after path translation, the call will be (roughly) equivalent to:
+
+  $c->sub_request( $translated_path, {}, @args );
 
 Notice that the stash will always be empty. This behavior could be configurable
 in the future through an additional switch - for now, this behavior guarantees a
-common interface for plugins.
+common interface for all plugins.
 
 =cut
 
diff --git a/lib/Catalyst/View/Component/SubInclude/Visit.pm b/lib/Catalyst/View/Component/SubInclude/Visit.pm
index b5fd93b..bc7fe01 100644
--- a/lib/Catalyst/View/Component/SubInclude/Visit.pm
+++ b/lib/Catalyst/View/Component/SubInclude/Visit.pm
@@ -40,14 +40,22 @@ render subinclude contents.
 
 This method is only supported when using L<Catalyst> version 5.71000 or newer.
 
+B<WARNING: As of Catalyst version 5.71000, this plugin doesn't work for chained 
+actions with captured arguments>. Apparently, C<visit> doesn't handle this type 
+of actions yet.
+
 =head1 CLASS METHODS
 
 =head2 C<generate_subinclude( $c, $path, @args )>
 
-This will translate to the following call:
+This is (roughly) equivalent to the following call:
 
   $c->visit( $path, @args );
 
+But it will handle all the nasty details such as localizing the stash, 
+parameters and response body. This is necessary to keep behavior consistent 
+with the other plugins.
+
 =cut
 
 sub generate_subinclude {