Document the keep_stash option for each plugin

Documented the subtile changes in behaiour of keep_stash in
each plugin

diff --git a/lib/Catalyst/View/Component/SubInclude.pm b/lib/Catalyst/View/Component/SubInclude.pm
index 6d04c87..33c2b06 100644 (file)
--- a/lib/Catalyst/View/Component/SubInclude.pm
+++ b/lib/Catalyst/View/Component/SubInclude.pm
@@ -81,11 +81,25 @@ By default, the C<SubRequest> plugin will be used. This can be changed in the
 view's configuration options (either in the config file or in the view module
 itself).
 
-Configuration file example:
+    __PACKAGE__->config(
+        subinclude_plugin => 'ESI',
+        subinclude => {
+            'SubRequest' => {
+                keep_stash => 1,
+            },
+            'HTTP::POST' => {
+                class => 'HTTP',
+                http_method => 'POST',
+                ua_timeout => '10',
+                uri_map => {
+                    '/foo/' => 'http://www.foo.com/',
+                },
+            },
+        },
+    );
 
-  <View::TT>
-      subinclude_plugin   ESI
-  </View::TT>
+You can change each plugins' configuration through the keys in the 'subinclude'
+config key (example above)
 
 =head2 C<set_subinclude_plugin( $plugin )>
 

diff --git a/lib/Catalyst/View/Component/SubInclude/SubRequest.pm b/lib/Catalyst/View/Component/SubInclude/SubRequest.pm
index a34e4e6..469808a 100644 (file)
--- a/lib/Catalyst/View/Component/SubInclude/SubRequest.pm
+++ b/lib/Catalyst/View/Component/SubInclude/SubRequest.pm
@@ -63,9 +63,28 @@ 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 all plugins.
+Notice that the stash will be empty by default. This behavior is configurable
+(see below).
+
+=head1 CONFIGURATION
+
+=head2 keep_stash
+
+You can choose to not localize the stash for SubRequests' subinclude calls. The subrequest
+will have the same stash as the request that spawned it. Configure the keep_stash key
+in your view:
+
+    __PACKAGE__->config(
+        subinclude => {
+            'SubRequest' => {
+                keep_stash => 1,
+            },
+        }
+    );
+
+Note: the stash that the subrequest recieves is a shallow copy of the original stash. That
+means that changes to values of keys on the first level of the stash will be lost when the
+subrequest call returns. Don't count on this behaviour, as it may change in the future.
 
 =cut
 

diff --git a/lib/Catalyst/View/Component/SubInclude/Visit.pm b/lib/Catalyst/View/Component/SubInclude/Visit.pm
index 3144499..88e883c 100644 (file)
--- a/lib/Catalyst/View/Component/SubInclude/Visit.pm
+++ b/lib/Catalyst/View/Component/SubInclude/Visit.pm
@@ -52,6 +52,25 @@ 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.
 
+=head1 CONFIGURATION
+
+=head2 keep_stash
+
+You can choose to not localize the stash for Visits' subinclude calls. The subrequest
+will have the same stash as the request that spawned it. Configure the keep_stash key
+in your view:
+
+    __PACKAGE__->config(
+        subinclude => {
+            'Visit' => {
+                keep_stash => 1,
+            },
+        }
+    );
+
+Note: changes in the stash during a Visit subinclude will be visible after the include 
+returns.
+
 =cut
 
 has keep_stash => (