[Catalyst-commits] r10856 - trunk/Catalyst-Plugin-Session-State-URI/lib/Catalyst/Plugin/Session/State

[autarch at dev.catalyst.perl.org]

Author: autarch
Date: 2009-07-11 18:53:39 +0000 (Sat, 11 Jul 2009)
New Revision: 10856

Modified:
   trunk/Catalyst-Plugin-Session-State-URI/lib/Catalyst/Plugin/Session/State/URI.pm
Log:
Revise some docs in State::URI


Modified: trunk/Catalyst-Plugin-Session-State-URI/lib/Catalyst/Plugin/Session/State/URI.pm
===================================================================
--- trunk/Catalyst-Plugin-Session-State-URI/lib/Catalyst/Plugin/Session/State/URI.pm	2009-07-11 18:41:07 UTC (rev 10855)
+++ trunk/Catalyst-Plugin-Session-State-URI/lib/Catalyst/Plugin/Session/State/URI.pm	2009-07-11 18:53:39 UTC (rev 10856)
@@ -344,8 +344,7 @@
 
 =head1 NAME
 
-Catalyst::Plugin::Session::State::URI - Saves session IDs by rewriting URIs
-delivered to the client, and extracting the session ID from requested URIs.
+Catalyst::Plugin::Session::State::URI - Use URIs to pass the session id between requests
 
 =head1 SYNOPSIS
 
@@ -358,31 +357,37 @@
 
 =head1 DESCRIPTION
 
-In order for L<Catalyst::Plugin::Session> to work the session ID needs to be
-stored on the client, and the session data needs to be stored on the server.
+In order for L<Catalyst::Plugin::Session> to work the session ID needs
+to be available on each request, and the session data needs to be
+stored on the server.
 
-This plugin cheats and instead of storing the session id on the client, it
-simply embeds the session id into every URI sent to the user.
+This plugin puts the session id into URIs instead of something like a
+cookie.
 
+By default, it rewrites all outgoing URIs, both redirects and in
+outgoing HTML, but you can exercise control over exactly which URIs
+are rewritten.
+
 =head1 METHODS
 
 =over 4
 
 =item session_should_rewrite
 
-This method is consulted by C<finalize>. The body will be rewritten only if it
-returns a true value.
+This method is consulted by C<finalize>, and URIs will be rewritten
+only if it returns a true value.
 
-This method will B<not> return true unless C<<
-$c->config->{session}{rewrite_body} >> or C<<
-$c->config->{session}{rewrite_redirect} >> is true. Both of these
-parameters default to true. To globally disable rewriting simply set
-these parameters to false.
+Rewriting is controlled by the C<< $c->config->{session}{rewrite_body}
+>> and C<< $c->config->{session}{rewrite_redirect} >> config settings,
+both of which default to true.
 
-If C<< $c->config->{session}{no_rewrite_if_cookie} >> is true (the default),
-L<Catalyst::Plugin::Session::State::Cookie> is also in use, and the user agent
-sent a cookie for the sesion then this method will return false.
+To globally disable rewriting simply set these parameters to false.
 
+If C<< $c->config->{session}{no_rewrite_if_cookie} >> is true,
+L<Catalyst::Plugin::Session::State::Cookie> is also in use, and the
+user agent sent a cookie for the sesion then this method will return
+false. This parameter also defaults to true.
+
 =item session_should_rewrite_body
 
 This method checks C<< $c->config->{session}{rewrite_body} >>
@@ -390,7 +395,8 @@
 
 =item session_should_rewrite_type
 
-Whether or not the content type of the body should be rewritten.
+This method determines whether or not the body should be rewritten,
+based on its content type.
 
 For compatibility this method will B<not> test the response's content type
 without configuration. If you want to do that you must provide a list of valid
@@ -399,7 +405,8 @@
 
 =item session_should_rewrite_redirect
 
-Whether or not to rewrite the C<Location> header of the response.
+This method determines whether or not to rewrite the C<Location>
+header of the response.
 
 This method checks C<< $c->config->{session}{rewrite_redirect} >>
 first. If this is true, it then checks if the status code is a number
@@ -429,11 +436,13 @@
 
 =item uri_with_sessionid $uri_text, [ $sid ]
 
-By path style rewriting, it will appends C</-/$sessionid> to the uri path.
+When using path style rewriting (the default), it will append
+C</-/$sessionid> to the uri path.
 
 http://myapp/link -> http://myapp/link/-/$sessionid
 
-By param style rewriting, it will add a parameter key/value pair after the uri path.
+When using param style rewriting, it will add a parameter key/value
+pair after the uri path.
 
 http://myapp/link -> http://myapp/link?$param=$sessionid