X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=4db76b0a12dfd726660e73e53ca5636d561bf18e;hp=cde45f603a435edd86068158101f60145bc86020;hb=31e9c5ef62da7e7aab68a5dc4b4650e3e2ff307e;hpb=bbddff000787154dd9130f45634da8ef06529d86

diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod
index cde45f6..4db76b0 100644
--- a/lib/Catalyst/Manual/Cookbook.pod
+++ b/lib/Catalyst/Manual/Cookbook.pod
@@ -11,7 +11,7 @@ Yummy code like your mum used to bake!
 =head1 Basics
 
 These recipes cover some basic stuff that is worth knowing for
-catalyst developers.
+Catalyst developers.
 
 =head2 Delivering a Custom Error Page
 
@@ -127,7 +127,7 @@ reference.
   package MyApp::Controller::Foo;
   use Moose;
   use namespace::autoclean;
-  BEGIN { extends 'Catalyst::Controller';
+  BEGIN { extends 'Catalyst::Controller' };
   ## Write data into the session
 
   sub add_item : Local {
@@ -212,7 +212,7 @@ See also L<Config::General|Config::General>.
 
 =head1 Skipping your VCS's directories
 
-Catalyst uses Module::Pluggable to load Models, Views and Controllers.
+Catalyst uses Module::Pluggable to load Models, Views, and Controllers.
 Module::Pluggable will scan through all directories and load modules
 it finds.  Sometimes you might want to skip some of these directories,
 for example when your version control system makes a subdirectory with
@@ -221,7 +221,7 @@ Catalyst skips subversion and CVS directories already, there are other
 source control systems.  Here is the configuration you need to add
 their directories to the list to skip.
 
-You can make catalyst skip these directories using the Catalyst config:
+You can make Catalyst skip these directories using the Catalyst config:
 
   # Configure the application
   __PACKAGE__->config(
@@ -234,7 +234,7 @@ and other options.
 
 =head1 Users and Access Control
 
-Most multiuser, and some single user web applications require that
+Most multiuser, and some single-user web applications require that
 users identify themselves, and the application is often required to
 define those roles.  The recipes below describe some ways of doing
 this.
@@ -243,7 +243,7 @@ this.
 
 This is extensively covered in other documentation; see in particular
 L<Catalyst::Plugin::Authentication> and the Authentication chapter
-of the Tutorial at L<Catalyst::Manual::Tutorial::Authorization>.
+of the Tutorial at L<Catalyst::Manual::Tutorial::06_Authorization>.
 
 =head2 Pass-through login (and other actions)
 
@@ -278,7 +278,7 @@ verification>.
 =item Authorization
 
 Making sure the user only accesses functions you want them to
-access. This is done by checking the verified users data against your
+access. This is done by checking the verified user's data against your
 internal list of groups, or allowed persons for the current page.
 
 =back
@@ -305,17 +305,17 @@ Examples:
 
 A Storage backend contains the actual data representing the users. It
 is queried by the credential verifiers. Updating the store is not done
-within this system, you will need to do it yourself.
+within this system; you will need to do it yourself.
 
 Examples:
 
- DBIC     - Storage using a database.
+ DBIC     - Storage using a database via DBIx::Class.
  Minimal  - Storage using a simple hash (for testing).
 
 =head3 User objects
 
 A User object is created by either the storage backend or the
-credential verifier, and filled with the retrieved user information.
+credential verifier, and is filled with the retrieved user information.
 
 Examples:
 
@@ -324,7 +324,7 @@ Examples:
 =head3 ACL authorization
 
 ACL stands for Access Control List. The ACL plugin allows you to
-regulate access on a path by path basis, by listing which users, or
+regulate access on a path-by-path basis, by listing which users, or
 roles, have access to which paths.
 
 =head3 Roles authorization
@@ -341,8 +341,8 @@ pass it these values.
 
 =head3 Checking roles
 
-Role checking is done by using the C<< $c->check_user_roles >> method,
-this will check using the currently logged in user (via C<< $c->user
+Role checking is done by using the C<< $c->check_user_roles >> method.
+This will check using the currently logged-in user (via C<< $c->user
 >>). You pass it the name of a role to check, and it returns true if
 the user is a member.
 
@@ -373,17 +373,17 @@ the user is a member.
                  },
              },
          },
-     },   
+     },
   );
 
   package MyApp::Controller::Root;
   use Moose;
   use namespace::autoclean;
-  
+
   BEGIN { extends 'Catalyst::Controller' }
-  
+
   __PACKAGE__->config(namespace => '');
-  
+
   sub login : Local {
      my ($self, $c) = @_;
 
@@ -412,11 +412,11 @@ the user is a member.
 
 =head3 Using authentication in a testing environment
 
-Ideally, to write tests for authentication/authorization code one
-would first set up a test database with known data, then use
+Ideally, to write tests for authentication/authorization code one would
+first set up a test database with known data, then use
 L<Test::WWW::Mechanize::Catalyst> to simulate a user logging
-in. Unfortunately the former can be rather awkward, which is why it's
-a good thing that the authentication framework is so flexible.
+in. Unfortunately this can be rather awkward, which is why it's a good
+thing that the authentication framework is so flexible.
 
 Instead of using a test database, one can simply change the
 authentication store to something a bit easier to deal with in a
@@ -424,9 +424,10 @@ testing environment. Additionally, this has the advantage of not
 modifying one's database, which can be problematic if one forgets to
 use the testing instead of production database.
 
-Alternatively, if you want to authenticate real users, but not have to worry about
-their passwords, you can use L<Catalyst::Authentication::Credential::Testing>
-to force all users to authenticate with a global password.
+Alternatively, if you want to authenticate real users, but not have to
+worry about their passwords, you can use
+L<Catalyst::Authentication::Credential::Testing> to force all users to
+authenticate with a global password.
 
 =head3 More information
 
@@ -437,9 +438,9 @@ L<Catalyst::Plugin::Authentication> has a longer explanation.
 =head3 Introduction
 
 Authorization is the step that comes after
-authentication. Authentication establishes that the user agent is
-really representing the user we think it's representing, and then
-authorization determines what this user is allowed to do.
+authentication. Authentication establishes that the user agent is really
+representing the user we think it's representing, and then authorization
+determines what this user is allowed to do.
 
 =head3 Role Based Access Control
 
@@ -460,7 +461,7 @@ With this action, anyone can just come into the moose cage and feed
 the moose, which is a very dangerous thing. We need to restrict this
 action, so that only a qualified moose feeder can perform that action.
 
-The Authorization::Roles plugin let's us perform role based access
+The Authorization::Roles plugin lets us perform role based access
 control checks. Let's load it:
 
     use parent qw/Catalyst/;
@@ -508,7 +509,7 @@ administration).
 
 Checking for roles all the time can be tedious and error prone.
 
-The Authorization::ACL plugin let's us declare where we'd like checks
+The Authorization::ACL plugin lets us declare where we'd like checks
 to be done automatically for us.
 
 For example, we may want to completely block out anyone who isn't a
@@ -559,7 +560,7 @@ If this action does not exist, an error will be thrown, which you can
 clean up in your C<end> private action instead.
 
 Also, it's important to note that if you restrict access to "/" then
-C<end>, C<default>, etc will also be restricted.
+C<end>, C<default>, etc. will also be restricted.
 
    MyApp->acl_allow_root_internals;
 
@@ -580,11 +581,14 @@ can be used outside of Catalyst, e.g.  in a cron job). It's trivial to
 write a simple component in Catalyst that slurps in an outside Model:
 
     package MyApp::Model::DB;
+
     use base qw/Catalyst::Model::DBIC::Schema/;
+
     __PACKAGE__->config(
         schema_class => 'Some::DBIC::Schema',
         connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}];
     );
+
     1;
 
 and that's it! Now C<Some::DBIC::Schema> is part of your
@@ -597,9 +601,9 @@ See L<Catalyst::Model::DBIC::Schema>.
 =head2 Create accessors to preload static data once per server instance
 
 When you have data that you want to load just once from the model at
-server load instead of for each request, use mk_group_accessors to
+startup, instead of for each request, use mk_group_accessors to
 create accessors and tie them to resultsets in your package that
-inherits from DBIx::Class::Schema
+inherits from DBIx::Class::Schema:
 
     package My::Schema;
     use base qw/DBIx::Class::Schema/;
@@ -623,12 +627,12 @@ inherits from DBIx::Class::Schema
 and now in the controller, you can now access any of these without a
 per-request fetch:
 
-    $c->stash->{something} = $c->model('My::Schema')->schema->ACCESSORNAMEn;
+    $c->stash->{something} = $c->model('My::Schema')->schema->ACCESSORNAME;
 
 
 =head2 XMLRPC
 
-Unlike SOAP, XMLRPC is a very simple (and imo elegant) web-services
+Unlike SOAP, XMLRPC is a very simple (and elegant) web-services
 protocol, exchanging small XML messages like these:
 
 Request:
@@ -731,7 +735,7 @@ enforce a specific one.
 =head1 Views
 
 Views pertain to the display of your application.  As with models,
-catalyst is uncommonly flexible.  The recipes below are just a start.
+Catalyst is uncommonly flexible.  The recipes below are just a start.
 
 =head2 Catalyst::View::TT
 
@@ -741,8 +745,8 @@ display your data; you can choose to generate HTML, PDF files, or plain
 text if you wanted.
 
 Most Catalyst applications use a template system to generate their HTML,
-and though there are several template systems available, Template
-Toolkit is probably the most popular.
+and though there are several template systems available,
+L<Template Toolkit|Template> is probably the most popular.
 
 Once again, the Catalyst developers have done all the hard work, and
 made things easy for the rest of us. Catalyst::View::TT provides the
@@ -993,7 +997,7 @@ Then you need a template. Here's the one from Agave:
 
 =head3 Using XML::Feed
 
-A more robust solution is to use XML::Feed, as was done in the Catalyst
+A more robust solution is to use L<XML::Feed>, as was done in the Catalyst
 Advent Calendar. Assuming we have a C<view> action that populates
 'entries' with some DBIx::Class iterator, the code would look something
 like this:
@@ -1080,36 +1084,6 @@ set the appropriate content type and disposition.
 Controllers are the main point of communication between the web server
 and your application.  Here we explore some aspects of how they work.
 
-=head2 Extending RenderView (formerly DefaultEnd)
-
-The recommended approach for an C<end> action is to use
-L<Catalyst::Action::RenderView> (taking the place of
-L<Catalyst::Plugin::DefaultEnd>), which does what you usually need.
-However there are times when you need to add a bit to it, but don't want
-to write your own C<end> action.
-
-You can extend it like this:
-
-To add something to an C<end> action that is called before rendering
-(this is likely to be what you want), simply place it in the C<end>
-method:
-
-    sub end : ActionClass('RenderView') {
-      my ( $self, $c ) = @_;
-      # do stuff here; the RenderView action is called afterwards
-    }
-
-To add things to an C<end> action that are called I<after> rendering,
-you can set it up like this:
-
-    sub render : ActionClass('RenderView') { }
-
-    sub end : Private {
-      my ( $self, $c ) = @_;
-      $c->forward('render');
-      # do stuff here
-    }
-
 =head2 Action Types
 
 =head3 Introduction
@@ -1125,7 +1099,7 @@ decides which URLs they map to.
 =head3 Type attributes
 
 Each action is a normal method in your controller, except that it has an
-L<attribute|http://search.cpan.org/~nwclark/perl-5.8.7/lib/attributes.pm>
+L<attribute|attributes>
 attached. These can be one of several types.
 
 Assume our Controller module starts with the following package declaration:
@@ -1325,23 +1299,24 @@ will both be called when visiting
 You can put root actions in your main MyApp.pm file, but this is deprecated,
 please put your actions into your Root controller.
 
-=head3 More Information
+=head3 Flowchart
 
-L<http://dev.catalyst.perl.org/wiki/FlowChart>
+A graphical flowchart of how the dispatcher works can be found on the wiki at
+L<http://dev.catalyst.perl.org/attachment/wiki/WikiStart/catalyst-flow.png>.
 
-=head2 DRY Controllers with Chained actions.
+=head2 DRY Controllers with Chained actions
 
 Imagine that you would like the following paths in your application:
 
 =over
 
-=item B</cd/<ID>/track/<ID>>
+=item B<< /cd/<ID>/track/<ID> >>
 
 Displays info on a particular track.
 
 In the case of a multi-volume CD, this is the track sequence.
 
-=item B</cd/<ID>/volume/<ID>/track/<ID>>
+=item B<< /cd/<ID>/volume/<ID>/track/<ID> >>
 
 Displays info on a track on a specific volume.
 
@@ -1507,6 +1482,38 @@ information on passing arguments via C<forward>.)
 
   sub key1 : Chained('/')
 
+=head2 Extending RenderView (formerly DefaultEnd)
+
+The recommended approach for an C<end> action is to use
+L<Catalyst::Action::RenderView> (taking the place of
+L<Catalyst::Plugin::DefaultEnd>), which does what you usually need.
+However there are times when you need to add a bit to it, but don't want
+to write your own C<end> action.
+
+You can extend it like this:
+
+To add something to an C<end> action that is called before rendering
+(this is likely to be what you want), simply place it in the C<end>
+method:
+
+    sub end : ActionClass('RenderView') {
+      my ( $self, $c ) = @_;
+      # do stuff here; the RenderView action is called afterwards
+    }
+
+To add things to an C<end> action that are called I<after> rendering,
+you can set it up like this:
+
+    sub render : ActionClass('RenderView') { }
+
+    sub end : Private {
+      my ( $self, $c ) = @_;
+      $c->forward('render');
+      # do stuff here
+    }
+
+
+
 =head1 Deployment
 
 The recipes below describe aspects of the deployment process,
@@ -1751,7 +1758,11 @@ than when using mod_perl.
 
 mod_fastcgi for Apache is a third party module, and can be found at
 L<http://www.fastcgi.com/>.  It is also packaged in many distributions,
-for example, libapache2-mod-fastcgi in Debian.
+for example, libapache2-mod-fastcgi in Debian. You will also need to install
+the L<FCGI> module from cpan.
+
+Important Note! If you experience difficulty properly rendering pages,
+try disabling Apache's mod_deflate (Deflate Module), e.g. 'a2dismod deflate'.
 
 =head4 2. Configure your application